Forem: OktaDev

Selecting the Best Authorization for Your API Integrations

OktaDev — Wed, 03 May 2023 15:09:00 +0000

Integrating with an API lets you power up your code by knowing what the API knows and doing what the API can do. The catch is that most APIs can't and shouldn't let just anybody access your important resources. Just as humans log in to access resources, programs accessing APIs must obtain proper authorization.

Your application can use two types of authorization mechanisms when calling Okta APIs from your Okta integration, each with its pros and cons:

API Tokens
OAuth 2.0

Let's better understand the two types, how they work, and when to use them.

Table of Contents

Authentication and Authorization using OAuth 2.0 + OpenID Connect (OIDC)
OAuth 2.0 Client Credentials
Decide which API authorization mechanism to use
Learn more about connecting to Okta APIs using OAuth Client Credentials

API Tokens

If you've connected with APIs before, you've probably copied a token and pasted it into the Authorization header of your HTTP request. Token authorization has several notable drawbacks, including when connecting to Okta APIs.

You can create API tokens from the Okta Admin Console. The Admin Console only shows you the token value upon creation, so you'll need to capture the value and securely persist it in a credentials manager. When you use the API token, you'll add it to the Authorization header of the call using the proprietary SSWS scheme.

GET /api/v1/groups?limit=10 HTTP/1.1
Authorization: SSWS api_token
Accept: application/json
Host: dev-1234567.okta.com

When an Okta user creates an API token, it has all of the user's permissions, which are rarely the best choice for an automated workflow. The user represented by the token becomes a single point of failure:

The automation may break if their permissions are reduced, or the user leaves the organization.
If the user's permissions are increased, the automation may silently gain the ability to cause unexpected problems if it has a bug.

All Okta API tokens automatically expire after being unused for 30 days to mitigate the security risks of old tokens falling into the wrong hands. A user can revoke tokens anytime from the Admin Console, and deleting no longer needed tokens is a good idea.

Considerations for using API tokens

It can be tempting to create a service account in Okta and use an API token from the service account, but this approach only moves the underlying problem rather than solving it. Managing access to the service account is complex, and mistakes can cause problems wherever the service account has access. Additionally, if the service account's token accidentally becomes publicized, anyone who gets the token can impersonate the service account.

When to use API tokens

Due to these constraints, API tokens are never the preferred authorization method for Okta's APIs. If you're ever in a situation where you "have to" use API tokens in production because OAuth or a service integration won't work, we'd love to hear about it! Let us know in the comments below, or discuss the challenges with your Okta representative.

OAuth 2.0 Client Credentials

OAuth has a standard flow for machine-to-machine communication called Client Credentials, the preferred way for processes without user input to communicate to Okta APIs. Using OAuth mechanisms enables you to use a well-known standardized format with fantastic support in libraries, frameworks, and languages of your choice. You can create an API Services application in the Okta Admin Console or use the Okta CLI.

If you haven't used OAuth Client Credentials before, a quick overview is as follows:

You'll create the Okta API Services application and configure the Okta API Scopes you want this application to have. When you make the Okta application, you'll receive a Client ID and a Client Secret to add to your Okta configuration in your program.
Your program calls the authorization server's token endpoint to exchange the Client ID and Client Secret for an access token. The access token contains the Okta API Scopes allowed. There may be Okta SDKs that help support this token call for you, depending on your language and framework. > Note > If you have a custom authorization server, such as when using a Okta Developer Edition org, you'll have to use signed JSON Web Token (JWT) using a JSON Web Key Set (JWKS). Read more about how to do this on the Implement OAuth for Okta developer documentation.
When you use the access token to call Okta APIs, you'll add the token to the Authorization header using the Bearer scheme.

GET /api/v1/groups?limit=10 HTTP/1.1
Authorization: Bearer access_token
Accept: application/json
Host: dev-1234567.okta.com

Considerations with using OAuth

The preferred method is using OAuth to call Okta APIs. It's more secure, and using widely available standards makes the calling process require less manual code. You'll configure the scopes you want the process to access, which aren't tied to a specific user. But you'll need to get the access token before making the API call.

When to use OAuth authorization

You should use OAuth as the preferred authorization mechanism for communication with Okta APIs, including machine-to-machine communications. A widely accepted industry standard like OAuth affords the most security and scope flexibility.

But, if you create an API Service application in Okta to share it outside of your organization, you delegate the scope configuration to the customer as part of their process of setting up an API Service application. There's a temptation for potential customers to either allow too much access or, conversely, limit access, causing frustrations that your integration needs fixes to work as intended.

Use API Service Integrations

API Service Integrations powers up your API integration applications using OAuth! Your API Integration becomes more discoverable to potential customers with improved handling for scopes. You can submit your integration to the Okta Integration Network (OIN), which makes your integration available in the OIN catalog. Potential customers can find your integration to add to their Okta org. Plus, as part of the submission process, you define the scopes your integration needs beforehand. Customers can see those scopes in the OIN catalog. Transparency in the required resources will help them feel more comfortable using your integration.

When creating integrations listed in the OIN, you can test your integration as part of the submission process. The OIN Manager provides a mechanism to create a local service app instance in your org to test your integration before you finalize the submission.

Decide which API authorization mechanism to use

When calling Okta APIs, we recommend using OAuth 2.0, and API Service Integrations if you create an API integration for the OIN. If you have limitations using OAuth 2.0 for your use case, use API Tokens.

Learn more about connecting to Okta APIs using OAuth Client Credentials

API tokens are the simplest, but this simplicity makes them too limited for production applications' security and reliability needs. OAuth client credentials require more understanding to set up but scale indefinitely for internal use. And for code intended for use by your customers to access their Okta tenant, API Service Integrations built on top of OAuth maximize flexibility and control.

If you found this post interesting, you might find these resources useful:

Remember to follow us on Twitter and subscribe to our YouTube channel for more great content. We'd also love to hear from you! Please comment below if you have any questions or want to share what topic you'd like to see next. Also, feel free to share your experience connecting to Okta APIs. We want to ensure our developers have the necessary resources and good experience integrating with Okta!

Jointly authored with

E. DunhamFollow

/edunham

Build a React App with Firebase Serverless Functions

OktaDev — Tue, 28 Jun 2022 14:17:53 +0000

Firebase is an exciting cloud platform from Google available to businesses today. Firebase connects everything from simple static websites to IoT devices to AI and machine learning platforms. The platform provides various services to facilitate these connections, like storage and authentication.

In this tutorial, you will learn about two core Firebase products: Cloud Functions for Firebase and Firebase Hosting. Hosting is for deploying static web applications. Functions are the Firebase serverless platform. You will create a static application using React that authenticates users via Okta's React library. After obtaining an access token from Okta's authorization server, you will use a Firebase function to exchange the Okta token for a Firebase token and sign in the user using Firebase's authentication structure. You will obtain additional user information by calling the userInfo endpoint on your Okta authorization server and including that data in your Firebase token. Finally, you will create another function endpoint to handle a simple HTTP request that requires an authenticated user.

Once you've built your application, you will deploy it to the Firebase platform for public consumption using the Firebase CLI.

Prerequisites

Okta offers Authentication and User Management APIs that reduce development time with instant-on, scalable user infrastructure. Okta's intuitive API and expert support make it easy for developers to authenticate, manage, and secure users and roles in any application.

If you wish, you can follow along with the GitHub repository found here.

oktadev / okta-react-firebase-serverless-example

React application with Okta authentication using Firebase functions deployed to Firebase

Build a React App with Firebase Serverless Functions

This repository shows you how to build a React application secured by Okta and deploy it to Firebase. It also shows you how to set up Functions in Firebase to exchange and Okta accessToken for a Firebase token and then call a secured route using Firebase auth.

Please read Build a React App with Firebase Serverless Functions to see how it was created.

Prerequisites:

Okta has Authentication and User Management APIs that reduce development time with instant-on, scalable user infrastructure. Okta's intuitive API and expert support make it easy for developers to authenticate, manage and secure users and roles in any application.

Visual Studio Code

Getting Started

To pull this example, first create an empty github repo. Next run the following commands:

git clone --bare https://github.com/oktadev/okta-react-firebase-serverless-example.git
cd okta-react-firebase-serverless-example
npm ci

…

View on GitHub

Add authentication using OIDC

Before you begin, you’ll need a free Okta developer account. Install the Okta CLI and run okta register to sign up for a new account. If you already have an account, run okta login. Then, run okta apps create. Select the default app name, or change it as you see fit. Choose Single-Page App and press Enter.

Use http://localhost:4280/login/callback for the Redirect URI and set the Logout Redirect URI to http://localhost:4280.

What does the Okta CLI do?
The Okta CLI will create an OIDC Single-Page App in your Okta Org. It will add the redirect URIs you specified and grant access to the Everyone group. It will also add a trusted origin for http://localhost:4280. You will see output like the following when it’s finished:

Okta application configuration:
Issuer:    https://dev-133337.okta.com/oauth2/default
Client ID: 0oab8eb55Kb9jdMIr5d6

NOTE: You can also use the Okta Admin Console to create your app. See Create a React App for more information.

The CLI outputs the Issuer and Client ID. You'll need those coming up.

Create your Firebase project

Next, open the Firebase console and click Add Project. Give your project a name, preferably okta-firebase. For now, you can turn off the analytics and create the project. Once that's completed, you'll be able to access the project dashboard.

First, click the Upgrade button next to the Spark option at the bottom of your screen. Change your plan to Blaze and if you wish, set a billing budget for $1 to let you know when you are incurring a charge. Blaze is pay-as-you-go, and the rates are pretty generous for hobby projects. You shouldn't incur any charges at this time, but the budget will let you know if you do.

Click the settings wheel next to Project Overview and click Project settings. At the bottom of the overview page, there's a prompt to Select a platform to get started and select web app (it will look like </>). Give your app the nickname okta-firebase-demo and select Also set up Firebase Hosting for this app. Click Register app, and in a moment you will see some JavaScript code for setting up your Firebase app.

Hold onto this information as you will need it in your app. Click through the rest of the wizard and return to your console. Again go to the Project settings section and navigate to the Service accounts tab. Click Generate new private key and let that file download. You will need this in your Firebase Function shortly.

Finally, click the Build>Authentication in the side nav and click Get Started. Pressing the Get Started button generates a Web API Key that is required for using the auth features.

Create your front end in React

Next, create your React app.

npx create-react-app@5 okta-firebase
cd okta-firebase

The npx command will scaffold a new React version 18 application for you.

Next, you will need to install a few dependencies to help you.

npm i @okta/okta-react@6.4.3
npm i @okta/okta-auth-js@6.2.0
npm i react-router-dom@5.3.0
npm i bootstrap@5.1.3
npm i firebase@9.8.1

First, you want to install the @okta/okta-react package to assist in authenticating users and obtaining the tokens from the Okta authorization server. This package will help you access the authentication state, direct users to the Okta login page, and handle any callbacks.

@okta/okta-react relies on the @okta/okta-auth-js package, so you need to install it.

Next, you want to install react-router-dom. This package will set up the callback route for you and any other routes you may need.

Finally, you will use the firebase package to call the various platform features in Firebase, such as functions and authentication.

Add a file called .env in your root directory and replace the code with the following.

REACT_APP_OKTA_ISSUER=https://{yourOktaDomain}/oauth2/default
REACT_APP_OKTA_CLIENTID={yourClientID}
REACT_APP_FIREBASE_APIKEY={yourFirebaseAPIKey}
REACT_APP_FIREBASE_AUTHDOMAIN={yourFirebaseAuthDomain}
REACT_APP_FIREBASE_PROJECTID={yourFirebaseProjectID}
REACT_APP_FIREBASE_STORAGEBUCKET={yourFirebaseStorageBucket}
REACT_APP_FIREBASE_MESSAGINGSENDERID={yourFirebaseMessagingSenderID}
REACT_APP_FIREBASE_APPID={yourFirebaseAppID}
REACT_APP_ENV=production

You obtained the Okta values when you created your application using the Okta CLI earlier. Your Okta domain is part of the Issuer. The Firebase values came from the configuration you copied when you first created your application.

There is currently a known error in React 18 with the Okta React library where multiple rerenders can lead to an error message in the oktaAuth object. Work on fixing this error is ongoing. In the meantime, you can work around it by taking React out of strict mode. Replace the code in your index.js file with the following code.

import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';
import reportWebVitals from './reportWebVitals';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
    <App />
);

// If you want to start measuring performance in your app, pass a function
// to log results (for example: reportWebVitals(console.log))
// or send to an analytics endpoint. Learn more: https://bit.ly/CRA-vitals
reportWebVitals();

Next, open your App.js file and replace the code with the following.

import "./App.css";

import { BrowserRouter as Router } from "react-router-dom";
import AppWithRouterAccess from "./AppWithRouterAccess";
import 'bootstrap/dist/css/bootstrap.min.css';


function App() {

  return (
    <Router>      
      <AppWithRouterAccess />
    </Router>
  );
}

export default App;

You are replacing the default code with a Router and an AppWithRouterAccess that you will write next. Open a new file called AppWithRouterAccess.jsx and add the following code.

import "./App.css";

import { Route, useHistory } from "react-router-dom";
import { OktaAuth, toRelativeUrl } from "@okta/okta-auth-js";
import { Security, LoginCallback } from "@okta/okta-react";

import Home from "./Home";

const {
  REACT_APP_OKTA_ISSUER,
  REACT_APP_OKTA_CLIENTID
} = process.env;

const oktaAuth = new OktaAuth({
  issuer: REACT_APP_OKTA_ISSUER,
  clientId: REACT_APP_OKTA_CLIENTID,
  redirectUri: window.location.origin + "/login/callback",
  scopes: ['openid', 'profile', 'email']
});

function AppWithRouterAccess() {
  const history = useHistory();

  const restoreOriginalUri = async (_oktaAuth, originalUri) => {
    history.replace(toRelativeUrl(originalUri || "/", window.location.origin));
  };

  return (
    <Security oktaAuth={oktaAuth} restoreOriginalUri={restoreOriginalUri}>
      <Route path="/" component={Home} />
      <Route path="/login/callback" component={LoginCallback} />
    </Security>
  );
}

export default AppWithRouterAccess;

This file will define your routes and establish the /login/callback route for Okta to handle signing in your users.

Finally, add the Home.jsx file to your application with the following code.

import React, { useState } from "react";

import { useOktaAuth } from "@okta/okta-react";

import { initializeApp } from "firebase/app";
import { getAuth, signInWithCustomToken, signOut } from "firebase/auth";
import {
  getFunctions,
  httpsCallable,
  connectFunctionsEmulator,
} from "firebase/functions";

function Home() {
  const [reportCardData, setReportCardData] = useState();

  const [selectedSemester, setSelectedSemester] = useState("Spring 2022");
  const { oktaAuth, authState } = useOktaAuth();

  const login = async () => oktaAuth.signInWithRedirect();
  const logout = async () => {
    signOut(auth);
    oktaAuth.signOut("/");
  };

  const {
    REACT_APP_FIREBASE_APIKEY,
    REACT_APP_FIREBASE_AUTHDOMAIN,
    REACT_APP_FIREBASE_PROJECTID,
    REACT_APP_FIREBASE_STORAGEBUCKET,
    REACT_APP_FIREBASE_MESSAGINGSENDERID,
    REACT_APP_FIREBASE_APPID,
    REACT_APP_ENV,
  } = process.env;

  const firebaseConfig = {
    apiKey: REACT_APP_FIREBASE_APIKEY,
    authDomain: REACT_APP_FIREBASE_AUTHDOMAIN,
    projectId: REACT_APP_FIREBASE_PROJECTID,
    storageBucket: REACT_APP_FIREBASE_STORAGEBUCKET,
    messagingSenderId: REACT_APP_FIREBASE_MESSAGINGSENDERID,
    appId: REACT_APP_FIREBASE_APPID,
  };

  const app = initializeApp(firebaseConfig);
  const functions = getFunctions(app);

  const auth = getAuth();

  if (REACT_APP_ENV === "development") {
    connectFunctionsEmulator(functions, "localhost", 5001);
  }

  const getGrades = async () => {
    const getGradesCall = httpsCallable(functions, "getGrades");
    const resp = await getGradesCall({
      name: selectedSemester.split(" ")[0],
      year: selectedSemester.split(" ")[1],
    });

    setReportCardData(resp.data);
  };

  const exchangeOktaTokenForFirebaseToken = async () => {
    const exchangeToken = httpsCallable(
      functions,
      "exchangeOktaTokenForFirebaseToken"
    );

    const resp = await exchangeToken({
      accessToken: authState.accessToken.accessToken
    });

    await signInWithCustomToken(auth, resp.data.firebaseToken);
  };

  if (authState?.isAuthenticated) {
    exchangeOktaTokenForFirebaseToken();
  }

  return (
    <div className="App">
      <main role="main" className="inner cover container">
        <nav className="navbar navbar-expand-lg navbar-light bg-light ">
          <ul className="nav navbar-nav ml-auto navbar-right ms-auto">
            <li>
              {auth?.currentUser && (
                <button
                  className="btn btn-outline-secondary my-2 my-sm-0"
                  onClick={logout}
                >
                  Logout
                </button>
              )}

              {!auth?.currentUser && (
                <button className="btn btn-outline-secondary" onClick={login}>
                  Login
                </button>
              )}
            </li>
          </ul>
        </nav>

        {!auth?.currentUser && (
          <div>
            <p className="lead">
              In order to use this application you must be logged into your Okta
              account
            </p>
            <p className="lead">
              <button className="btn btn-primary" onClick={login}>
                Login
              </button>
            </p>
          </div>
        )}
        {auth?.currentUser && (
          <div>
            <h1 className="cover-heading">
              Please select a semester to get your report card
            </h1>

            <div className="row">
              <div className="col-2">
                <select
                  className="form-select"
                  value={selectedSemester}
                  onChange={(e) => {
                    setSelectedSemester(e.target.value);
                  }}
                >
                  <option value="Fall 2021">Fall 2021</option>
                  <option value="Spring 2021">Spring 2021</option>
                  <option value="Fall 2022">Fall 2022</option>
                  <option value="Spring 2022">Spring 2022</option>
                </select>
              </div>
              <div className="col-2">
                <button className="btn btn-primary" onClick={getGrades}>
                  Get Grades
                </button>
              </div>
            </div>

            {reportCardData && (
              <>
                <p>
                  <b>Name: </b> {reportCardData.name}
                </p>
                <p>
                  <b>School: </b> {reportCardData.school}
                </p>
                <p>
                  <b>Semester: </b> {reportCardData.semester} -{" "}
                  {reportCardData.year}
                </p>

                <table className="table table-striped">
                  <thead>
                    <tr>
                      <th className="text-start"> Course </th>
                      <th> Score </th>
                      <th> Letter Grade </th>
                    </tr>
                  </thead>
                  <tbody>
                    {reportCardData.grades.map((grade, i) => {
                      return (
                        <tr key={i}>
                          <td className="text-start">{grade.course}</td>
                          <td>{grade.score}</td>
                          <td>{grade.letterGrade}</td>
                        </tr>
                      );
                    })}
                  </tbody>
                </table>
              </>
            )}
          </div>
        )}

        <footer
          className="bg-light text-center fixed-bottom"
          style={{
            width: "100%",
            padding: "0 15px",
          }}
        >
          <p>
            A Small demo using <a href="https://developer.okta.com/">Okta</a> to
            Secure an{" "}
            <a href="https://firebase.google.com/">
              Firebase hosted application{" "}
            </a>{" "}
            with a serverless{" "}
            <a href="https://firebase.google.com/docs/functions">function</a>
          </p>
          <p>
            By <a href="https://github.com/nickolasfisher">Nik Fisher</a>
          </p>
        </footer>
      </main>
    </div>
  );
}

export default Home;

This page will handle both the authenticated and unauthenticated states. If the user is not authenticated, they are presented with a screen requesting them to do so. If the user is authenticated, they can getGrades by selecting a semester from the drop-down and calling the server.

The getGrades function ensures the user is authenticated using the build-in authentication function in Firebase. Firebase also integrates with authentication tokens from providers such as Okta. To utilize this functionality, you will mint a Firebase authentication token using an Okta authentication token. Okta returns an accessToken to the client when the user logs in. The client then passes the accessToken to a Firebase function called exchangeOktaTokenForFirebaseToken. In this Cloud Function for Firebase, you verify the token and return a Firebase token to log the user in. Then subsequent calls to the functions will treat that user as logged in to Firebase.

At this point, you can use the npm run start command to run your app locally. You'll see a few console errors from Firebase, and you'll see Login buttons. Notice that you're able to authenticate with Okta now, but the login process doesn't call Firebase yet, so your login is still incomplete.

Make your React application ready for Firebase

Now you are ready to prepare your application for Firebase. If you haven't done so yet, please install the Firebase CLI.

npm install -g firebase-tools@11.1.0

To log in with your Google account, you may need to run firebase login.

Next, run the command firebase init to start the initialization of your project.

Select both of the following features:

Functions: Configure a Cloud Functions directory and its files
Hosting: Configure files for Firebase Hosting and (optionally) set up GitHub Action deploys

Select Use an existing project and select your okta-firebase-{ID} project

After a moment, you'll see prompts to set up Firebase functions. Select the following options:

Language - Javascript
EsLint - No (You should use this in production-ready applications.)
When prompted to install dependencies say Yes

Next, select the following options to set up hosting.

What do you want to use as your public directory? - build
Configure as a single-page app? yes
Setup automatic builds? no

Before deploying your application, you must run the build command on your React app to prepare it properly. By configuring your app as a SPA, you tell the Firebase CLI to edit the configuration to redirect to /index.html.

Add authenticated Firebase functions

You should notice that a new folder called functions has been added to your directory. There, you will see some Firebase config stuff and a file called index.js. You're going to add the code for two functions.

First, you will need one that accepts an Okta token and returns a Firebase token for the client to use. To verify the token, you will use the @okta/jwt-verifier package from Okta.

The second function will accept arguments from the client, namely the semester, and use that along with some information from the token to build report card data for the client to use to create the report card.

Start by navigating to your functions directory and installing your dependencies.

cd functions
npm i @okta/jwt-verifier@2.3.0

The @okta/jwt-verifier will verify your JWT from Okta when calling the exchangeOktaTokenForFirebaseToken function.

Next, copy the keys file you downloaded from the Firebase console earlier and add it to your functions folder. Make a note of the name, as you will need that shortly.

Add a file to your functions folder called grades.js and add the following code.

const getGrades = (user, semester) => {
  return {
    name: user.name,
    school: getFakeUniversityName(user.email),
    semester: semester.name,
    year: semester.year,
    grades: grades
      .filter((r) => r.year == semester.year)
      .filter((r) => r.semester == semester.name),
  };
};

const getFakeUniversityName = (email) => {
  const number = Math.floor(Math.random() * 2);
  const domain = parseDomain(email);

  switch (number) {
    case 0:
      return "University of " + domain;
    case 1:
      return domain + " State University";
    default:
      return "University of " + domain;
  }
};

const parseDomain = (email) => {
  const emailParts = email.split("@");
  const domainParts = emailParts[1].split(".");

  let name = "";

  domainParts.forEach((part, i) => {
    if (i > 0) {
      name += " ";
    }
    if (i + 1 < domainParts.length) {
      name += part.charAt(0).toUpperCase() + part.slice(1);
    }
  });

  return name;
};

const grades = [
  {
    course: "Calculus 1",
    score: 72,
    letterGrade: "C",
    year: 2021,
    semester: "Fall",
  },
  {
    course: "Intro to Ballroom Dance",
    score: 94,
    letterGrade: "A",
    year: 2021,
    semester: "Fall",
  },
  {
    course: "Computer Science 101",
    score: 65,
    letterGrade: "F",
    year: 2021,
    semester: "Fall",
  },
  {
    course: "Intro to Modern Physics",
    score: 88,
    letterGrade: "B",
    year: 2021,
    semester: "Fall",
  },

  {
    course: "Calculus 2",
    score: 84,
    letterGrade: "C",
    year: 2021,
    semester: "Spring",
  },
  {
    course: "Geometry",
    score: 97,
    letterGrade: "A",
    year: 2021,
    semester: "Spring",
  },
  {
    course: "Computer Science 101",
    score: 76,
    letterGrade: "C",
    year: 2021,
    semester: "Spring",
  },
  {
    course: "Physics II",
    score: 88,
    letterGrade: "B",
    year: 2021,
    semester: "Spring",
  },

  {
    course: "Calculus 3",
    score: 84,
    letterGrade: "C",
    year: 2022,
    semester: "Fall",
  },
  {
    course: "Abstract Algebra",
    score: 97,
    letterGrade: "A",
    year: 2022,
    semester: "Fall",
  },
  {
    course: "Computer Science 102",
    score: 76,
    letterGrade: "C",
    year: 2022,
    semester: "Fall",
  },
  {
    course: "Public Speaking",
    score: 88,
    letterGrade: "B",
    year: 2022,
    semester: "Fall",
  },

  {
    course: "Adv Calculus",
    score: 84,
    letterGrade: "C",
    year: 2022,
    semester: "Spring",
  },
  {
    course: "Geometry",
    score: 97,
    letterGrade: "A",
    year: 2022,
    semester: "Spring",
  },
  {
    course: "Javascript in the Modern Web",
    score: 76,
    letterGrade: "C",
    year: 2022,
    semester: "Spring",
  },
  {
    course: "Cryptography",
    score: 88,
    letterGrade: "B",
    year: 2022,
    semester: "Spring",
  },
];

module.exports = { getGrades };

First, exchangeOktaTokenForFirebaseToken will provide a custom token from Firebase to use in your application. Firebase allows you complete control over your authentication via the signInWithCustomToken method you used on the client. You need to create a custom token using your service account. You downloaded your service account definition as a JSON file earlier. Now you can call createCustomToken from your auth object against your service account. This function requires a uid and optionally accepts other claims you may wish to add. Be mindful that Firebase reserves token names.

You can then obtain a token from the Okta authorization server and present it to the Firebase function to be verified using the OktaJwtVerifier. If the Okta token is valid, you will call your Okta authorization server's userInfo endpoint to obtain additional information about your user. You can include this information in your Firebase token as its custom claims. Then you can use the firebaseApp object to create your token with those claims. You'll return this token to the client and sign in with it.

Next, you have the getGrades function. You check context.auth to see if the user is logged in. If they aren't, you are throwing an error. If they are, allow the user to access the grades data in that file.

There are two different ways to set up functions in Firebase, onCall and onRequest. onRequest gives you a more raw form of handling the incoming call. You'd need to set up your CORS code, your authentication, and all the good stuff that the onCall wrapper takes care of for you. For example, context.auth is provided because you used the onCall, whereas through onRequest you would need to obtain this information manually.

Test your app locally using Firebase emulators

Now you are ready to test your application locally through the Firebase emulator. The emulator will make it so that your services can communicate as though they were deployed to Firebase.

First, edit your .env file to replace REACT_APP_ENV=production with REACT_APP_ENV=development. This change tells the application to connect to the emulator. Next, run the following commands in your project's root directory.

npm run build
firebase emulators:start

First, you need to build your application since Firebase expects your application to be in the build directory as you configured earlier. Next, it will create an emulator and deploy your function and web application to that emulator. By default, the web app deploys to localhost:5000 rather than the usual localhost:3000.

If you find that you have conflicts with the default ports that Firebase uses, you can update the firebase.json file entries for emulators.functions.port and emulators.hosting.port to ports that you have available. See below for an example firebase.json file that uses port 5002 for hosting and 5001 for functions.

{
  "hosting": {
    "public": "build",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ]
  },
  "functions": {
    "source": "functions"
  },
  "emulators": {
    "functions": {
      "port": 5001
    },
    "hosting": {
      "port": 5002
    },
    "ui": {
      "enabled": false
    }
  }
}

You'll need to open the Okta admin console and navigate to your Okta application to add these ports to the allowlist.

Open Okta Developer Portal and Sign in to Okta. Then press Admin to launch the admin console.

Navigate to Applications > Applications and find your Okta application for this project. Select it to edit. On the General tab, Edit the General Settings with the new ports. For example, if your Firebase hosting port is 5000, add http://localhost:5000/login/callback to Sign-in redirect URIs and http://localhost:5000 to your Sign-out redirect URIs. Update the port number based on your Firebase emulator settings and save.

There's one more place to add the new port in the Okta admin console. You'll add the port as a Trusted Origin so your app can complete the logout process. Navigate to Security > API and open the Trusted Origins tab. Press the + Add Origin button and add the new URL with the port, such as http://localhost:5000/. Select the Redirect and CORS checkboxes and save, then return to your application.

At this point, you should be able to log in to Okta, exchange your token for a Firebase token, select a semester, and click Get Grades to see your report card generate.

Deploy your application to Firebase

Once this works, you are ready to deploy your application to Firebase. First, set your .env entry for REACT_APP_ENV back to production if you had set it to development. You may need to run the npm run build command once more in case you've made any edits or changes. Once complete, run the command firebase deploy from your root directory.

After completing this step, your CLI will provide a URL to your application. You should see your application running on Firebase if you click that. But, Okta won't work at this point. You need to go back to your Okta admin portal, under your application, and add {yourFirebaseDomain}/login/callback to your Sign-in redirect URIs, {yourFirebaseDomain} to your Sign-out redirect URIs to the General Settings tab of your Okta application, and add {yourFirebaseDomain} as a Trusted Origin

Now return to your application in Firebase and click Sign In to ensure Okta is hooked up correctly. Once you are signed in, you should be able to select a semester and click Get Grades to see your report card generated.

Review your React app with authenticated Firebase functions

In this article, you learned how to create and deploy a web application to Google Firebase. You also learned how to build Firebase functions as a backend for your web application. Finally, you learned how to secure your SPA using Okta and exchange your Okta access token for a Firebase token that it will know how to use in its pipeline. Here are some related articles that might also be of interest:

Make sure you follow us on Twitter and subscribe to our YouTube channel. Please comment below if you have any questions or want to share what tutorial you'd like to see next.

Original post written by Nickolas Fisher for the Okta Developer blog.

A Beginner's Guide to Application Security

OktaDev — Fri, 13 May 2022 15:44:40 +0000

Over the past decade, and even more swiftly since the time of the COVID-19 pandemic, digital transformation of the workplace has primarily been driven by applications. Apps have become an integral part of everyday life for many organizations.

Modern applications are complex. Their functionality frequently relies on APIs and third-party integrations, leading to an increased attack surface and more security vulnerabilities. A data breach or an attacker exploiting a security weakness can permanently damage your business. It's crucial that you understand and secure your application's infrastructure.

There are a number of actions you can take to keep attackers away. Following are some tips and best practices for a more secure application.

Understanding application security

Application security, or AppSec, as it's commonly known, takes place throughout the development lifecycle. It's the process of creating applications that are secure from both internal and external threats. Internal threats can range from simple human error to malicious acts. External threats, which include data breaches, malware, and phishing attacks, can be constant and costly. It's estimated that distributed denial-of-service (DDoS) attacks alone will grow to 15.4 million by 2023.

As attackers target applications ever more aggressively, keeping them secure plays a vital role in a holistic cybersecurity strategy. Application security is necessary to avoid financial and legal repercussions, protect your organization's reputation, and build trust with your customers and partners.

Application security concepts

There are a few concepts you should understand before you develop an application security strategy. Learning these will help you avoid common pitfalls or ineffective techniques that could compromise the security of your application.

OWASP Top 10

The Open Web Application Security Project (OWASP) online community studies and reports on web application security. The OWASP Top 10 report lists the most critical security vulnerabilities an application can face.

The list—based on survey data from cybersecurity professionals—is determined by the frequency and likelihood of a vulnerability, how easy it is to detect, and the impact it can have on your organization.

OWASP's report can help you assess areas of your application that present higher potential risk. It provides example attack scenarios to show how various vulnerabilities work, as well as guidelines for avoiding these attacks.

Below are the top ten security vulnerabilities as noted in the latest OWASP report from 2021:

Broken access control
Cryptographic failures
Injection
Insecure design
Security misconfiguration
Vulnerable and outdated components
Identification and authentication failures
Software and data integrity failures
Security logging and monitoring failures
Server-side request forgery

Authentication basics

Authentication is a necessary feature of modern applications because it prevents unauthorized users from accessing and misusing sensitive information.

When you start developing an application, you might be tempted to build your own authentication system to save costs or maintain full control. However, creating an effective authentication system is a challenging job with many factors to consider. If done poorly, it can cause severe consequences.

Instead, there are authentication solutions available to help you enhance the security of your application. Platforms like Okta or Auth0 provide you with powerful identity services tailored to your needs.

These services offer a high level of expertise and keep updating their technology to stay ahead of new cyberattack forms. Using third-party software can help you avoid pitfalls and save money in the long run. When you rely on a platform, you can focus on building and running your applications.

For more about the advantages of a pre-built identity solution, check this whitepaper on the advantages of a pre-built identity solution.

External user management

A user management system is an essential part of application security. It allows you to collect, store, and manage user data for a smoother user registration process, enhanced authentication, and better password management. You can also use it to control who can access particular aspects of your infrastructure, including networks, devices, and applications.

As with authentication, you might want to build your own user management system. However, these are complex systems to create that generally require dedicated teams, especially for enterprise-level applications. You could run into issues such as failing to sanitize user input or being stuck with a frustrating registration process.

With an external user management system, you'll get a robust, out-of-the-box solution that adjusts to your needs while handling tricky tasks like scaling or regulatory compliance. This can also help you reduce overall user management costs since you won't need to pay in-house developers to do the work.

Up-to-date programs are a best practice

To achieve the highest level of security, you should ensure that your applications and their dependencies are always up to date. Updates contain patches to fix security vulnerabilities that malicious actors could exploit.

Update the antivirus programs on your devices and your firewalls. You can also use asset management software to detect outdated programs.

Secure communication protocols

Be sure your site or application uses Hypertext Transfer Protocol Secure (HTTPS). It adds a security layer to traditional HTTP by encrypting the data exchanged between computers and servers over the internet. For example, if your user fills out a form with personal information, even if the data is stolen, it won't have any value to the attacker because it cannot easily be decoded.

HTTPS is so important that it's become the de facto industry standard. All major web browsers discourage users from visiting non-HTTPS websites, and search engines penalize those websites in search results.

HTTPS protects data with the Transport Layer Security (TLS) protocol, which uses a public-key encryption system to ensure that applications communicate and exchange data safely.

Learn more about how to get started with HTTPS in this series.

Security testing tools

Use security testing to detect vulnerabilities in your application. Testing can help you protect your applications from data breaches and avoid performance issues. You can also determine your application's level of security stability and avoid future problems.

Testing can be a time-consuming ongoing process, but there are solutions to help you test efficiently. Two popular testing tools are vulnerability assessment and penetration testing.

Vulnerability assessment or scanner tools review your application to see if it's vulnerable to security attacks. They identify, analyze, and help you solve security risks.

Penetration testing (or pen testing) is a white-hat hacking technique you can use to detect security flaws. You imitate the steps a cyber attacker would take in order to identify and fix vulnerabilities before real attackers can discover them.

Certifications in app security

You might be inspired to learn even more about application security. If that's the case, consider pursuing certification, so you can develop expertise in cloud security. This in-demand skill set will benefit you as well as your company or organization.

Use your knowledge

Application security needs to be a top priority for developers. Modern applications often run on multiple networks and connect to the cloud, increasing the number of potentially problematic access points for attackers.

Many organizations are familiar with security best practices but may not understand the concepts behind them. Using this knowledge, you can implement the solutions described above to achieve great results.

Check out these posts for more information about application security:

Webinar: Securing Remote Access: The Intersection of Identity and Network Security
A Brief History of Zero Trust Security
You can search a collection of recent Okta Developer blog posts that cover aspects of app security or check out this free book about API security written by members of the Okta Dev Advocacy team back in 2019.

If you have any questions about this post, please add a comment below. For more interesting content, follow @oktadev on Twitter, connect with us on LinkedIn, and subscribe to our YouTube channel.

Original post written by Alex Doukas for the Okta Developer blog.

How to Build and Deploy a Serverless React App on Azure

OktaDev — Thu, 14 Apr 2022 14:56:48 +0000

Microsoft's Azure platform has as many high-tech products as anyone could ever want, including the Azure Static Web Apps service. As the name suggests, the platform hosts static web apps that don't require a back end. Azure supports React, Angular, Vue, Gatsby, and many more, out of the box.

However, you may run into situations where you want some back-end support, such as when you need the backend to run one or two API calls. For this task, Azure offers the Functions platform as well. Functions is a serverless computing platform that supports .NET, Node.js, Python, etc. It takes care of setting up a server, builds logging and exception handling, and provides a high availability environment at a reasonable price.

This tutorial will show you how to create a React application and deploy it to Azure Static Web Apps. The application will be on the Azure free tier, so you will not be able to rely on the built-in authentication providers that connect Azure and Okta to handle the authentication. Therefore, you will use the okta-react package from Okta to secure your single page application (SPA) manually. Once the user authenticates, they'll be able to upload an image and receive a badge from a serverless Azure function.

This serverless function will handle the work of accepting the input image from the SPA and using a template to create a personalized badge for the user. Since you will be using the free version of Azure Static Web Apps, you will have to deploy the function as a Managed Azure Function.

You will write your application in Visual Studio Code and use the Azure extensions for Functions and Static Web Apps.

Prerequisites

Okta has Authentication and User Management APIs that reduce development time with instant-on, scalable user infrastructure. Okta's intuitive API and expert support make it easy for developers to authenticate, manage and secure users and roles in any application.

Visual Studio Code
- Azure Functions VS Code Extension
- Azure Static Web Apps VS Code Extension

If you want to see the code, you can download it or fork it from the example on GitHub.

oktadev / okta-react-azure-functions-example

How to Build and Deploy a Serverless React App on Azure Example

This repository shows you how to build a Static Web App in React for Azure and how to add a Function in Azure for a serverless backend. Please read How to Build and Deploy a Serverless React App on Azure to see how it was created.

Prerequisites:

Node.js
Azure Account
- Azure Subscription to use for the Azure Account
GitHub Account
Okta CLI

Okta has Authentication and User Management APIs that reduce development time with instant-on, scalable user infrastructure. Okta's intuitive API and expert support make it easy for developers to authenticate, manage and secure users and roles in any application.

Visual Studio Code
- Azure Fucntions VS Code Extension
- Azure Static Web Apps VS Code Extension

Getting Started

To pull this example, first create an empty GitHub repo. Next run the following commands:

git

…

View on GitHub

Create your Okta application

Use http://localhost:4280/login/callback for the Redirect URI and set the Logout Redirect URI to http://localhost:4280.

Okta application configuration:
Issuer:    https://dev-133337.okta.com/oauth2/default
Client ID: 0oab8eb55Kb9jdMIr5d6

NOTE: You can also use the Okta Admin Console to create your app. See Create a React App for more information.

Create your React application

The next step is to build your React application as a static web app. Begin as you would with most React apps by running npx create-react-app azure-static-app. After a few moments, your application will be ready to run. Once this happens, delete the .gitignore file and the .git folder that create-react-app produced. At this time, there is no way to prevent the task from adding these, but they will conflict with the Azure git files you will add soon.

Start by adding the dependencies you will need. cd azure-static-app into your React directory and run the following commands.

npm i @okta/okta-auth-js@6.2.0
npm i @okta/okta-react@6.4.3
npm i react-router-dom@5.3.0
npm i bootstrap@5.1.3

The @okta/okta-react library is the principal package you will use to log the user in. This package relies on @okta/okta-auth-js to work. react-router-dom will help secure your routes and provide a route for the login/callback. Finally, you will use Bootstrap to style the site.

Next, replace the contents of App.js with the following code.

import React from "react";
import { BrowserRouter as Router } from "react-router-dom";
import AppWithRouterAccess from "./AppWithRouterAccess";
import "bootstrap/dist/css/bootstrap.min.css";

const App = () => {
  return (
    <Router>
      <AppWithRouterAccess />
    </Router>
  );
};

export default App;

The code you've added makes the following changes:

Imports Bootstrap to style the application
prepare the application to use the AppWithRouterAccess method that you'll soon create
Wraps the BrowserRouter component from react-router-dom so you can access the Routes and Route objects in child components

Add the AppWithRouterAccess.jsx file to your src directory and add the following code to it.

import "./App.css";

import { Route, useHistory } from "react-router-dom";
import { OktaAuth, toRelativeUrl } from "@okta/okta-auth-js";
import { Security, LoginCallback } from "@okta/okta-react";

import Home from "./Home";

const oktaAuth = new OktaAuth({
  issuer: "https://{yourOktaDomain}/oauth2/default",
  clientId: "{yourOktaClientId}",
  redirectUri: window.location.origin + "/login/callback",
});

function AppWithRouterAccess() {
  const history = useHistory();

  const restoreOriginalUri = async (_oktaAuth, originalUri) => {
    history.replace(toRelativeUrl(originalUri || "/", window.location.origin));
  };

  return (
    <Security oktaAuth={oktaAuth} restoreOriginalUri={restoreOriginalUri}>
      <Route path="/" component={Home} />
      <Route path="/login/callback" component={LoginCallback} />
    </Security>
  );
}

export default AppWithRouterAccess;

This component creates the routes for your Home and LoginCallback components. It also initializes the OktaAuth object, which is passed into the Security component for the children to use. To do this, use the clientId and issuer that the Okta CLI returned when you created your Okta app and replace {yourOktaClientId} and {yourOktaDomain}. If you used a server other than your default authorization server, you will need to change the entire issuer, not just your domain.

Next, add Home.jsx to your src folder and add the following code.

import { useOktaAuth } from "@okta/okta-react";
import { useState } from "react";

function Home() {
  const { oktaAuth, authState } = useOktaAuth();

  const [image, setImage] = useState();
  const [display, setDisplay] = useState();

  const acceptImage = (e) => {
    setImage(e.target.files[0]);
  };

  const login = async () => oktaAuth.signInWithRedirect();
  const logout = async () => oktaAuth.signOut("/");

  const createBadge = async () => {
    var data = new FormData();
    data.append("file", image);

    // Ideally the Azure Function should call the `/userprofile` endpoint to get  
    // the user name instead of relying on the client to send it since the client
    // could manipulate the data
    data.append("firstLetter", authState.idToken.claims.name[0]);

    const resp = await fetch("api/CreateBadge", {
      method: "POST",
      headers: {
        "okta-authorization": "Bearer " + authState.accessToken.accessToken,
      },
      body: data,
    });

    const blob = await resp.blob();
    setDisplay(URL.createObjectURL(blob));
  };

  return (
    <div className="App">
      <main role="main" className="inner cover container">
        <nav className="navbar navbar-expand-lg navbar-light bg-light ">
          <ul className="nav navbar-nav ml-auto navbar-right ms-auto">
            <li>
              {authState?.isAuthenticated && (
                <button className="btn btn-outline-secondary my-2 my-sm-0" onClick={logout}>
                  Logout
                </button>
              )}

              {!authState?.isAuthenticated && (
                <button className="btn btn-outline-secondary" onClick={login}>
                  Login
                </button>
              )}
            </li>
          </ul>
        </nav>

        <h1 className="cover-heading">Create your Intergalactic Mining Federation badge</h1>

        {!authState?.isAuthenticated && (
          <div>
            <p className="lead">In order to use this application you must be logged into your Okta account</p>
            <p className="lead">
              <button className="btn btn-primary" onClick={login}>
                Login
              </button>
            </p>
          </div>
        )}
        {authState?.isAuthenticated && (
          <div>
            <p className="lead">To Create your badge, upload your image below</p>
            <input onChange={acceptImage} name="image" type="file" />
            <button className="btn btn-primary" onClick={createBadge}>
              Upload
            </button>
            <br />
            {display && <img className="pt-4" alt="your IMF badge" src={display}></img>}
          </div>
        )}

        <footer
          className="bg-light text-center fixed-bottom"
          style={{
            width: "100%",
            padding: "0 15px",
          }}
        >
          <p>
            A Small demo using <a href="https://developer.okta.com/">Okta</a> to Secure an{" "}
            <a href="https://azure.microsoft.com/en-us/services/app-service/static/">Azure Static Web App </a> with a serverless{" "}
            <a href="https://azure.microsoft.com/en-us/services/functions/">Function</a>
          </p>
          <p>
            By <a href="https://github.com/nickolasfisher">Nik Fisher</a>
          </p>
        </footer>
      </main>
    </div>
  );
}

export default Home;

This file contains the bulk of your logic. First, it provides Login/Logout functionality using the useOktaAuth hook. With this hook, you can determine the user's authenticated state. If the user is not authenticated, prompt them to do so; otherwise, you will allow them to use the badge creator.

The badge creator logic prompts users to upload a photo of themselves for the template. It then posts this to the nebulous api/CreateBadge. This route stands for the CreateBadge function that you will create later in this article. Azure will know how to find that route whether you're running this application locally on Azure's emulator or Azure's infrastructure. It will even be able to route to the appropriate environment on Azure's servers.

A note here: You might expect to send the accessToken in the Authorization header; however, Azure overwrites the Authorization header with its token by default. You can eliminate this step on the Azure standard pricing model by using the custom providers in the Static Web App and the Function. However, you will need to use this workaround on the free model.

In this tutorial, the client sends the username from the ID token. Ideally, the Azure Function should retrieve the username by making a call to the /userprofile endpoint. By having the Azure Function handle this, you can ensure you get the accurate username without relying on the client to send something potentially inaccurate.

One other note: Environment variables do not work at this time on Static Web Apps. If you attempt to use process.env.{variable} in your code and set it in the application settings, it will not work.

Finally, add StaticWebApp.config.json to your azure-static-app directory and add the code below.

{
    "navigationFallback": {
      "rewrite": "/index.html"
    }
}

This configuration file is necessary for single page apps to handle routing on the client. Specifically, you will need this for the login/callback route.

Test your React application

At this point, you can ensure your React application is working and connected to Okta properly. In the root of your React application, add a new file called .env and add the following code to it.

PORT=4280

The Azure emulator will run the application on 4280 by default, so we set up the Okta application to allow that port. However, React usually runs the application on port 3000. Using .env to set the port will enable us to override that behavior and run the app on 4280.

Next, run the npm run start command in your React application's directory. You should be able to see your home screen and log in to Okta, but you will not be able to use the image feature yet.

Write your Azure Serverless Function code

You'll need that api/CreateBadge endpoint to land somewhere. Open the Azure extension in VS Code, and use the Static Web Apps section to click Create HTTP Function. Select javascript as the language and name the function CreateBadge. The extension will create a new folder called api and another folder called CreateBadge with your Function code.

First, run cd ../api to enter the api folder (assuming you're still in azure-static-app folder). You can install your dependencies first.

npm i @okta/jwt-verifier@2.3.0
npm i canvas@2.9.0
npm i parse-multipart-data@1.2.1

parse-multipart-data will help parse the image from the request body. You will use canvas to modify the image. Finally, @okta/jwt-verifier will verify the token passed in the header to authenticate the user. As I mentioned before, but worth mentioning again, if you are using the standard pricing model, then the authentication can and should be handled in the Azure portal using a custom provider. However, you are stuck doing the work yourself on the free tier.

Open api/CreateBadge/index.js and replace the code there with the following.

const { createCanvas, loadImage } = require("canvas");
const { rename } = require("fs");
const querystring = require("querystring");

const templateWH = [394, 225];
const profilePictureStart = [22, 48];
const profilePictureWH = [97, 121];
const letterStart = [250, 205];

const multipart = require("parse-multipart-data");

badgeTemplateUrl = "https://i.imgur.com/50dOBYK.png";

const OktaJwtVerifier = require("@okta/jwt-verifier");

const oktaJwtVerifier = new OktaJwtVerifier({
  issuer: "https://{yourOktaDomain}/oauth2/default",
});

const getAuthToken = (req) => {
  const header = req.headers["okta-authorization"];
  const tokenParts = header.split(" ");
  const token = tokenParts.length > 0 ? tokenParts[1] : "";

  return token;
};

const drawImage = async (req) => {
  const bodyBuffer = Buffer.from(req.body);
  const boundary = multipart.getBoundary(req.headers["content-type"]);
  const parts = multipart.parse(bodyBuffer, boundary);

  const canvas = createCanvas(templateWH[0], templateWH[1]);
  const ctx = canvas.getContext("2d");

  // Ideally this Azure Function should call the `/userprofile` endpoint to get  
  // the user name instead of relying on the client to send it
  const firstLetter = parts.filter((r) => r.name === "firstLetter")[0].data.toString();

  const template = await loadImage(badgeTemplateUrl);
  ctx.drawImage(template, 0, 0, templateWH[0], templateWH[1]);

  ctx.font = "68px Calibri";
  ctx.fillStyle = "#fff";
  ctx.fillText(firstLetter, letterStart[0], letterStart[1]);

  const profileImage = await loadImage(parts[0].data);
  ctx.drawImage(profileImage, profilePictureStart[0], profilePictureStart[1], profilePictureWH[0], profilePictureWH[1]);

  return canvas;
};

module.exports = async function (context, req) {
  const accessToken = getAuthToken(req);
  const jwt = await oktaJwtVerifier.verifyAccessToken(accessToken, "api://default");

  const canvas = await drawImage(req);

  var stream = await canvas.pngStream();
  context.res.setHeader("Content-Type", "image/png");
  context.res.end(canvas.toBuffer("image/png"));
};

This file uses the OktaJwtVerifier to verify the token sent from the React front end. It does this by parsing the okta-authorization header. If the token is invalid, it will return a 403.

The other primary function of this code is to take the image uploaded by the user and modify a template image by adding the uploaded image to it. You will also pull the user's name from the JWT and replace the name on the badge with the first letter of the user's first name. If your name is "Okta Developers", you'll see "Agent O". Assuming this was all a success, you would return the image to the SPA to display to the user.

Deploy your application to Azure Static Web Apps and Azure Functions

Click into the Azure VS Code extension again, and under the Static Web Apps section, click Create Static Web App.... Follow the prompts and add the following information. If you are new to Azure, you'll first need to create a "Subscription". Then answer the prompts as shown below:

Azure Subscription Name - "My Azure Subscription"
Azure Web App name - azure-static-app
GitHub repo - azure-static-app
Commit Message - initial commit
Region - Select the region closest to you
Framework - React
Root of your app - azure-static-app
Root of your api (if asked) - api
Build - leave this blank

Everything will need a few moments to build. This process creates a new git repo on your GitHub account, configures the CI/CD for Azure Static Web Apps using GitHub Actions, creates your Azure Static Web App, and deploys your function and SPA code. Once it's complete, you should be able to navigate to your newly created site.

Edit your Okta application

You will need to configure your Okta application for your newly deployed application. You used your localhost settings when you first configured your app. Now you need to add your Azure settings as well.

Edit your application and under the Login section, add your Azure domain with the /login/callback endpoint to the Sign-in redirect URIs section. Next, add the domain's home page to your Sign-out redirect URIs section.

Next, navigate to Security > API and click Trusted Origins. Add your Azure domain to this list.

Run your application

Finally, navigate back to your Azure domain and log in using Okta. Select an image you want to use for your profile picture and click Upload. After a moment, your function should return your new badge.

Use the Azure emulator

If you've run into an error deploying and need to debug your project locally, you can use the Azure Static Web App emulator to tie your full product together. You'll need to install some npm packages to run both the web app and the API functions.

In the terminal, run the following commands to install the necessary packages:

npm install -g @azure/static-web-apps-cli azure-functions-core-tools
npm install -g azure-functions-core-tools@3 --unsafe-perm true

Navigate to the root directory of the project and run the following command to start the Static Web App emulator, run the web app in dev mode, and also run the API function:

swa start http://localhost:4280 --app-location azure-static-app --run="npm start" --api-location ./api --func-args="--javascript"

It's possible to run this app from the build directory, but you will lose the benefits of hot-reloading as you make changes.

Wrap up

In this tutorial, you learned how to create a React app and deploy it to Azure as a Static Web App. You also learned how to build a Function in Azure and call it from your Static Web App. Finally, you learned how to secure both the Function and the Static Web App using Okta.

Want to explore some related resources for building apps on the Azure platform? Take a look at some of these other Okta Developer blog posts.

Make sure you follow us on Twitter and subscribe to our YouTube channel. If you have any questions or want to share what tutorial you'd like to see next, please comment below.

Original post written by Nickolas Fisher for the Okta Developer blog.

A Comparison of Cookies and Tokens for Secure Authentication

OktaDev — Wed, 30 Mar 2022 14:28:27 +0000

Access control in websites and web applications is a top priority for security, but how you set up access depends on how you store the data to be authenticated. This, in turn, enables user authorization. Cookies and tokens are two common ways of setting up authentication.

Cookies are chunks of data created by the server and sent to the client for communication purposes. Tokens, usually referring to JSON Web Tokens (JWTs), are signed credentials encoded into a long string of characters created by the server. The main difference between cookies and tokens is their nature: tokens are stateless while cookies are stateful.

With this in mind, why is there a need to store authentication on the browser? Because HTTP is stateless, even if you authenticate with one request, the server essentially "forgets" that authentication with subsequent requests. Therefore, you need to supply the token/cookie on every request for authentication by the server. The frontend stores the token or cookie and uses it to make subsequent requests to the server until the cookie or token expires.

This article will examine the use of cookies or tokens for authentication, comparing the pros and cons of each method, so that you can determine which is best for your project.

About authentication

Authentication is the act of verifying user credentials in terms of either correctness or time.

Correctness: The user credentials are verified based on existing details. At the sign-in request, an authentication token is assigned to the user. It will be used to authorize the user and authenticate subsequent interactions with the application.
Time: The authentication token assigned to the user is only valid for a specific period of time. If the token becomes invalid, the user needs to be re-authenticated before access can be granted.

NOTE: The term "authentication token" is used here to describe any form of authentication credential that might be implemented by the application, not explicitly an access token.

The above instances aren't environment-specific and could be demonstrated visually on the frontend or the backend during API testing.

Why use authentication

There are two reasons why authentication is necessary to allow full access to an application:

Authentication establishes the identity of the user and verifies that the user is who (or what) it says it is. Authentication protects your resources by denying access to unauthenticated users.
Authentication gives each user a distinct identity, protecting your data and theirs. Applications that require users to create an account give each user a unique profile, which is what determines the data shown to the user. For example, PayPal requires users to sign in before displaying their account balance and transactions.

Generally, the process works like this:

You sign in.
The server verifies your sign-in details and assigns you an authentication token.
The authentication token is used to make a request to your homepage that displays your unique dashboard.

Both session cookies and access tokens allow users to make requests to the server without needing to re-authenticate at each request. The following is a comparison of the two.

What you should know about cookies

Session cookies are stateful elements. They contain data that the server sends to the browser for temporary use. The authentication data inside a cookie is stored on both the client and server. The server keeps track of active sessions in a database, while the browser holds the identifier to the active session. When a request is made to the server, the session ID is used to look up information such as user roles or privileges for authentication, in order to check if the session is still valid.

Advantages of cookies

Consider these key benefits:

Cookies use the same session across subdomains: They take a Domain argument: You specify the domain name for which the cookie is valid. Setting the domain name to yoursite.com allows the same session for the domain and subdomains.
They reduce manipulation by client-side JavaScript: You can restrict client-side access by setting the HttpOnly flag. This reduces the likelihood of cross-site scripting (XSS) attacks on your application, since most XSS attacks involve the use of malicious JS code.
They require little storage: Cookies use as little as 6 KB to store a simple user ID. Depending on what information you store in your cookie, you'll transmit a minimal amount of bytes with every request.
Finally, cookies are managed by the browser: This is automatic, so you don't have to worry about it.

The downside of cookies

Some of the disadvantages of cookies include:

Cross-site request forgery attacks (XSRF or CSRF): CSRF attacks are only possible with cookie-based session handling. The SameSite attribute allows you to decide whether cookies should be sent to third-party apps using the Strict or Lax settings. A strict setting can prevent CSRF attacks, but it can also contribute to a poor browser experience for the user. For example, say your site uses a cookie named tutorials_shown to determine whether a user has already seen specific tutorials in order to show them new ones every time they visit. If SameSite is set to Strict and someone follows a link to your site, the cookie will not be sent on that first request, and previously viewed tutorials will be shown. This creates a less personalized user experience.
Scaling issues: Since sessions are tied to a particular server, you can run into issues when scaling your application. In a load-balanced application, if a logged-in user is redirected to a new server, the existing session data is lost. To prevent this, sessions need to be stored in a shared database or cache. This increases the complexity of each interaction.
Not good for API authentication: APIs provide one-time resources for authenticated end-users and don't need to keep track of user sessions. Cookies don't work perfectly in this case, since they track and verify active sessions. Tokens, meanwhile, provide authentication with a unique identifier on every request to the API endpoints.

Cookies aren't the only way to store session IDs; other options include URLs and form fields. Cookies are more secure than those two, but how secure are cookies?

Cookies are only secure in an HTTPS connection. Enforcing the Secure flag ensures that cookies are only sent via an encrypted HTTPS connection. Use of HTTPS prevents disclosure of session ID in person-in-the-middle (MITM) attacks.
As noted earlier, cookies can be manipulated by client-side scripts (JavaScript or Visual Basic). This can be prevented by using the HttpOnly flag.

While cookies can be made secure by setting the appropriate attributes and following best practices, they can also be made insecure by neglecting these steps.

Structured security tokens

Tokens—or JWTs in this context—are stateless in nature, meaning the server doesn't need to keep a record of the token. Each token is self-contained, holding the information needed for verification and identification on the server.

Advantages of tokens

Here are some specific advantages of tokens:

Flexibility and ease of use: JWTs are easy to use. Their self-containing nature helps you achieve what you need for verification without database lookups. This makes JWTs more suitable to use in an API, since the API server doesn't need to keep track of user sessions.
Cross-platform capabilities: Because of their stateless nature, tokens can be seamlessly implemented on mobile platforms and internet of things (IoT) applications, especially in comparison to cookies..
Multiple storage options: Tokens can be stored in a number of ways in browsers or front-end applications.

If you use a browser's local storage, tokens can't be accessed by a subdomain. However, they can be accessed and manipulated by any JavaScript code on the webpage, as well as by browser plugins. This isn't a recommended method: first, it poses a security risk, plus you must manage the storage.

Session storage is another way to store tokens. The drawback is that the token is destroyed when the browser is closed.

Disadvantages of JWT tokens

Here are some downsides of tokens to be aware of:

Revocation: A JWT cannot be revoked. Even if a JWT leaks, it remains valid until it expires, resulting in a serious security hole. As a workaround, you must implement a deny-list technique that requires a more complex setup.
Need more space: A JWT might need 300+ bytes to store a simple user ID, because they store other data for authentication.
Stale: The information inside of a JWT represents a snapshot in time when the token was originally created. The associated user may now have different access levels or have been removed from the system altogether.

But what about the security of tokens?

JWTs are cryptographically signed and base64-encoded. They're only secure when they aren't exposed, so they should be treated like passwords.
A JWT can be viewed but not manipulated on the client side. You can take your token to jwt.io/, choose the algorithm you used to sign, and see the data. You just can't tamper with it because it's issued on the server.
The lifespan of a JWT should be kept short to limit the risk caused by a leaked token.

When to use cookies or tokens

In general, the choice between a session cookie or a structured token will depend on your use case. You should use cookies when you need to keep track of user interactions, such as with an e-commerce application or website. You can use tokens when building API services or implementing distributed systems.

For more information about cookies, tokens, or authentication in general, check out these posts:

Please comment below with any questions. For more interesting content, follow @oktadev on Twitter, find us on LinkedIn, or subscribe to our YouTube channel.

Original post written by Teniola Fatunmbi for the Okta Developer blog.

Creating a TypeScript React Application with Vite

OktaDev — Tue, 15 Mar 2022 19:31:05 +0000

Front-end applications are becoming ever bigger and more complex. It is not uncommon for a React app to have hundreds or even thousands of components. As the project size increases, build times become increasingly important. In large projects, you may have to wait up to a minute for the code to be translated and bundled into a production package run in the browser. The compile and load times for the development server are also a big issue for these projects. Changes in the code may only show up in the browser after a few seconds. These wait times have become a bottleneck that slows down development.

Vite addresses this problem by providing a development server and a lightning-fast build command. Vite, pronounced /vit/, is French for "quick," and this name describes the goal for this tool. The build command uses Rollup under the hood, which is preconfigured to create highly optimized code. The development server makes use of browser support for ES modules. Hot Module Replacement will instantly load any codebase changes into the browser.

Vite was originally developed for Vue, but you can also create React and Svelte projects out of the box. In this tutorial, I will show you how to create a TypeScript-based React application using Vite. The application will be a simple number conversion tool that converts decimal numbers to hexadecimal and binary. I won't assume any prior knowledge apart from a familiarity with JavaScript.

Prerequisites:

Using Vite to create the TypeScript React application

Before you start, you should have recent versions of Node and npm installed on your system. The first step is to use the Vite command to create a new application. This can be done using the npm init command without installing any additional software. Open a terminal in a folder of your choice and run the following command.

npm init vite@latest vite-number-conversion -- --template react-ts

If you are using an older version of npm (below version 7), you'll need to modify the command slightly.

npm init vite@2.8.0 vite-number-conversion --template react-ts

This command will generate a new folder vite-number-conversion and initialize it with the react-ts template. If you are asked to agree to install the create-vite package, simply answer with yes. This template creates a React project using TypeScript and all the configuration for tooling required to develop and build the project. Next, navigate into the new project folder and run the command below to install all the dependencies.

npm install

You will be using the React Router to manage navigation through your single-page app. Run the following command to install the additional dependency.

npm install -E react-router-dom@5.3.0 @types/react-router-dom@5.3.3

Now open your favorite IDE in the project folder. Feel free to browse around a little to get familiar with the code that Vite has generated. If you are familiar with create-react-app, you will notice that the differences are not that big on the surface. There is a Vite-specific configuration file, vite.config.ts, to tweak Vite's behavior. For now, leave it as it is, but we will get back to this file later.

Your React components are saved as .tsx files in the src/ folder. To keep things organized, create a new folder src/components and add a new file src/components/Home.tsx. This will be the component to show the application's home page. Paste the following contents into the file.

function Home() {
    return <div>
        <h1>Number Converter</h1>
    </div>
}

export default Home;

Next, create the component that contains the number conversion tool. Create another file src/components/Converter.tsx with the contents below.

import { useState } from 'react';

function Converter() {
    const [value, setValue] = useState<number>();
    const [origin, setOrigin] = useState<string>();
    const isDisabled = (base: string) => (origin !== undefined && origin !== base);

    const updateValue = (baseName: string, base: number) => 
        (e: React.ChangeEvent<HTMLInputElement>) => {
            if (e.target.value === "") {
                setValue((oldValue) => undefined);
                setOrigin((oldOrigin) => undefined);
            } else {
                setValue((oldValue) => {
                    const newValue = parseInt(e.target.value, base);
                    return isNaN(newValue) ? oldValue : newValue;
                });
                setOrigin((oldOrigin) => baseName);
            }
        }

    return <div className="Converter">
        <label>
            Decimal:
            <input type="string" 
                value={value?.toString(10) || ""}
                name="decimal" 
                onChange={updateValue("decimal", 10)} 
                disabled={isDisabled("decimal")}/>
        </label>
        <label>
            Hexadecimal:
            <input type="string" 
                value={value?.toString(16) || ""}
                name="hex" 
                onChange={updateValue("hex", 16)} 
                disabled={isDisabled("hex")}/>
        </label>
        <label>
            Binary:
            <input type="string" 
                value={value?.toString(2) || ""}
                name="binary" 
                onChange={updateValue("binary", 2)} 
                disabled={isDisabled("binary")}/>
        </label>
    </div>
}

export default Converter;

The Converter component contains three input fields, one for the decimal value, one for the hexadecimal value, and one for the binary value. It also uses two state variables. value contains the number that should be converted to the different formats, and origin includes the input field's name in which the user has entered a number. The idea is to disable the input elements filled automatically with the converted values—the isDisabled() callback controls which elements are disabled.

The updateValue() function is a little bit more tricky. It is a function that returns a callback configured with the name and the number-base of the input field. The callback takes the ChangeEvent and updates the component state according to the value in the input field. In the functional programming style, higher-order functions like updateValue() can provide a mechanism to implement configurable code without creating code repetition.

Next, open src/main.tsx and add the Router to the application. At the top of the file, add the following import.

import { BrowserRouter } from 'react-router-dom';

Then, modify the render function to look like the code below.

ReactDOM.render(
  <React.StrictMode>
    <BrowserRouter>
      <App />
    </BrowserRouter>
  </React.StrictMode>,
  document.getElementById('root')
)

To add the routes to the application, open src/App.tsx and replace its contents with the following code.

import './App.css'
import { Link, Route, Switch } from 'react-router-dom';
import Home from './components/Home';
import Converter from './components/Converter';

function App() {
  return (
    <div className="App">
      <nav>
        <div className="menu">
          <Link to="/">Home</Link>
          <Link to="/converter">Converter</Link>
        </div>
      </nav>
      <Switch>
        <Route exact path="/" component={Home} />
        <Route path="/converter" component={Converter} />
      </Switch>
    </div>
  )
}

export default App

The application is mostly complete, but it needs some styling. Open src/App.css and edit it to match the CSS below.

.App {
  text-align: center;
}

.App nav {
  display: flex;
  justify-content: space-between;
  background-color: #333333;
  color: #ffffff;
  padding: 0.5rem 1rem;
}

.App nav a {
  color: #ffffff;
  text-decoration: none;
  margin-left: 1rem;
  margin-right: 1rem;
}

.Converter {
  text-align: left;
  margin: 1rem 4rem;
}

.Converter label {
  display: block;
  margin-bottom: 1rem;
}

.Converter input {
  display: block;
  margin-top: 0.5rem;
}

Start it up and watch it run

Now, the fun begins! You are ready to start the application. Open the terminal in the project folder and run the following command.

npm run dev

If you are used to React applications built with create-react-app, you might expect to wait a few seconds before the development server starts. With Vite, I see the following message in less than a second.

  vite v2.8.4 dev server running at:

  > Local: http://localhost:3000/
  > Network: use `--host` to expose

  ready in 461ms.

You can now open your browser at http://localhost:3000/ and test the application. When I click the Converter link in the navigation bar, I see something like this.

I opened up the Developer Tools in Chrome to understand how Vite achieves these fast starting-up times. When you open up the Network tab and filter by JS requests, you will see many requests to individual JavaScript sources. You will even see the .tsx sources you just edited.

I then looked closer at App.tsx, and saw what is shown in the above image. When the development server is asked to serve a .tsx file, it will compile it on the fly into browser-compatible code. But it keeps all the import statements in place and uses the support for ES modules in the newer browsers. This way, the bundling stage is eliminated, and the loading times are significantly reduced.

Adding authentication with Okta to the application

A secure application needs user authentication to keep unauthorized users out of restricted areas. With Okta, it is easy to add authentication to your Vite application in just a few steps.

Use http://localhost:3000/callback for the Redirect URI and set the Logout Redirect URI to http://localhost:3000.

What does the Okta CLI do?
The Okta CLI will create an OIDC Single-Page App in your Okta Org. It will add the redirect URIs you specified and grant access to the Everyone group. It will also add a trusted origin for http://localhost:3000. You will see output like the following when it’s finished:

Okta application configuration:
Issuer:    https://dev-133337.okta.com/oauth2/default
Client ID: 0oab8eb55Kb9jdMIr5d6

NOTE: You can also use the Okta Admin Console to create your app. See Create a React App for more information.

Now you are ready to add the Okta libraries for React into your project. Open the terminal in the project folder and run the following command.

npm install -E @okta/okta-react@6.4.2 @okta/okta-auth-js@6.1.0

Vite needs some help resolving import aliases used by the Okta libraries. To make things work, open vite.config.ts and add the following entry to the configuration object.

resolve: {
  alias: [
    {
      find: "@okta/okta-auth-js",
      replacement: require.resolve("@okta/okta-auth-js/dist/okta-auth-js.umd.js"),
    },
  ],
}

If your IDE or build can't resolve require, you may need to add the @types/node library for the require method. In the terminal, add the library by running the following command:

npm i –save-dev @types/node

Now, open src/main.tsx and add the following code immediately after the import statements.

import { Security } from '@okta/okta-react';
import { OktaAuth, toRelativeUrl } from '@okta/okta-auth-js';

const oktaAuth = new OktaAuth({
  issuer: `https://{yourOktaDomain}/oauth2/default`,
  clientId: '{yourClientID}',
  redirectUri: `${window.location.origin}/callback`,
});

function restoreOriginalUri(oktaAuth: OktaAuth, originalUri: string) {
  window.location.replace(
    toRelativeUrl(originalUri || "/", window.location.origin)
  );
}

Here {yourClientID} is the client ID that you obtained earlier and {yourOktaDomain} is your Okta domain. Next, surround the BrowserRouter component with the Security component, passing in oktaAuth and restoreOriginalUri as parameters. The call to the render function should look something like this.

ReactDOM.render(
  <React.StrictMode>
    <Security oktaAuth={oktaAuth} restoreOriginalUri={restoreOriginalUri}>
      <BrowserRouter>
        <App />
      </BrowserRouter>
    </Security>
  </React.StrictMode>,
  document.getElementById('root')
)

Now that you have made the OktaAuth object available to your application, you are ready to create a secured route and configure the login process. Open src/App.tsx and add the following import.

import { LoginCallback, SecureRoute } from '@okta/okta-react';

Finally, convert the route that serves the Converter component to a secured route and add another route that handles the login callback from Okta. The code inside the Switch component should resemble the code below.

<Switch>
  <Route exact path="/" component={Home} />
  <SecureRoute path="/converter" component={Converter} />
  <Route path="/callback" component={LoginCallback} />
</Switch>

Congratulations, you are ready to power up the application again. If it is still not running, run the command below in the terminal.

npm run dev

Now, whenever you navigate to the Converter route, the application checks if you are authenticated. If not, it will redirect you to the Okta sign-in page, where you can enter your user credentials. After successfully logging in, you are able to access the application page you requested.

Learn more about React, TypeScript, and Okta

In this tutorial, I guided you through creating a TypeScript React application using Vite. Vite is a lightning-fast development server and package bundler that leverages modern ES module browser support and Hot Module Replacement—speeding up refresh times after changes to the codebase can significantly improve development productivity.

As an example, I showed you how to implement a number conversion utility that converts between decimal, hexadecimal, and binary formats. The application was secured using Okta authentication, and you have seen how this can be achieved in just a few lines of code.

If you want to learn more about React, TypeScript, or Okta authentication in JavaScript, please follow the links below.

You can find the code for this tutorial on GitHub at https://github.com/oktadev/okta-react-vite-number-converter-example.

oktadev / okta-react-vite-number-converter-example

React TypeScript App using Vite Example

This example app shows how to create a TypeScript-based React app using Vite and add authentication.

Please read Creating a TypeScript React Application with Vite to see how this app was created.

Prerequisites:

Node installed
An Okta Developer Account

Okta has Authentication and User Management APIs that reduce development time with instant-on, scalable user infrastructure. Okta's intuitive API and expert support make it easy for developers to authenticate, manage and secure users and roles in any application.

Getting Started

To install this example application, run the following commands:

git clone https://github.com/oktadeveloper/okta-react-vite-number-converter-example.git
cd okta-react-vite-number-converter-example
npm install

Create an OIDC App on Okta

Before you begin, you'll need a free Okta developer account. Install the Okta CLI and run okta register to sign up for a new account. If you already have an account, run okta login.

Then, run okta…

View on GitHub

If you liked this tutorial, chances are you like others we publish. Please follow @oktadev on Twitter and subscribe to our YouTube channel to get notified when we publish new developer tutorials.

Original post written by Holger Schmitz for the Okta Developer blog.

How to Create a React App with Storybook

OktaDev — Thu, 20 Jan 2022 23:02:35 +0000

UI designers and front-end developers are tasked with creating clean and consistent user interfaces. At the same time, testing is a cornerstone of software development. Each part of a software project is tested individually and isolated from the other elements in unit tests. This practice has been challenging to achieve in the context of user interfaces.

Now Storybook provides an open-source framework that lets you test UI components in isolation from the rest of the website. Storybook presents you with a browser of all the components in your web application. You can test each component independently and in different configurations. The tool runs as a separate application outside your main application, which means that you can test your components without worrying about application-specific dependencies or requirements.

In this tutorial, I will show you how to use Storybook to create a simple React application. The application will be a unit conversion app, and I will use Storybook to showcase the individual components and the application page itself. I will not assume any prior knowledge of React or Storybook. I will assume that you are familiar with JavaScript and Node, and have an up-to-date version of the npm packet manager installed on your computer.

Prerequisites:

Creating React components with Storybook

In this section, I will show you how to create a React application and implement components displayed in Storybook. These components will serve as the basis for the unit conversion application. To start, open a terminal in a folder of your choice and run the following command to create a new React application.

npx create-react-app@5 react-storybook --use-npm

The create-react-app command creates a new folder, react-storybook, and initialises a basic application skeleton. Next, turn this basic React app into a Storybook application. Navigate into the newly created folder and run the following command.

npx sb@6 init

When prompted, answer yes to install the sb package. Initializing Storybook will create a new folder, stories inside the src folder, and populate it with some pre-made demo components and stories to be used by Storybook. Open the project folder in your favourite IDE.

You can test out storybook straight away. Open a terminal session in the project folder and run the following command.

npm run storybook

The command runs the Storybook app and opens a browser tab (http://localhost:6006). For now, you will only see the components that Storybook installs by default. You can keep Storybook running while you develop your app.

Using your IDE, create a new file named src/stories/Components.jsx. This will be the module that will contain some basic UI components. For the sake of this tutorial, I will place all these components into a single module. In practice, you might want to spread them out over several files. Open src/stories/Components.jsx and paste in the following code.

import React, { useState } from 'react';
import PropTypes from 'prop-types';
import './Components.css';

export function Input({ size, type, label, name, placeholder, onChange }) {
  return (
    <label className={`input-component input-component--${size}`}>
      <span>{label}</span>
      <input
        type={type==='text' ? 'text' : 'number'}
        step={type==='floating-point' ? 'any' : undefined}
        name={name}
        placeholder={placeholder}
        onChange={onChange}
      />
    </label>
  );
};

Input.propTypes = {
  size: PropTypes.oneOf(['medium', 'large']),
  type: PropTypes.oneOf(['text', 'number', 'floating-point']),
  label: PropTypes.string.isRequired,
  name: PropTypes.string.isRequired,
  placeholder: PropTypes.string.isRequired,
  onChange: PropTypes.func,
};

Input.defaultProps = {
  size: 'medium',
  type: 'text',
  label: 'Enter a value',
  name: 'input',
  placeholder: 'Please enter a value',
  onChange: undefined
};

export function Select({ size, label, options, onChange }) {
  return (
    <label className={`select-component select-component--${size}`}>
      <span>{label}</span>
      <select className="select-component" onChange={onChange}>
        {options.map((option) => <option value={option.value}>{option.description}</option>)}
      </select>
    </label>
  );
};

Select.propTypes = {
  size: PropTypes.oneOf(['medium', 'large']),
  label: PropTypes.string.isRequired,
  options: PropTypes.arrayOf(PropTypes.shape({
    value: PropTypes.string.isRequired,
    description: PropTypes.string.isRequired
  })).isRequired,
  onChange: PropTypes.func,
};

Select.defaultProps = {
  size: 'medium',
  label: 'Options',
  options: []
};

export function Tabs({ children }) {
  const [active, setActive] = useState(0);

  const onTabClick = (newActive) => () => {
    setActive(() => newActive);
  };

  return (
    <div className="tabs-component">
      <div className="tabs-row">
        {children.map((child, index) => <div className={`tab ${index === active ? "active" : ""}`} onClick={onTabClick(index)}>{child.props.label}</div>)}
      </div>
      <div className="tabs-content">
        {children[active]}
      </div>
    </div>
  );
};

Tabs.propTypes = {
  children: PropTypes.instanceOf(Array).isRequired,
};

Tabs.defaultProps = {
  children: []
};

This module exports three components. Input is a configurable <input> element with a label for entering text or numbers, Select is a dropdown <select> element wrapped in a label, and Tabs is a component that shows its children in a separate tab. I am using the React feature propTypes to specify the properties that each React component expects as arguments, allowing Storybook to extract this meta-information and display it to the user. To provide a bit of styling for the components, create a file src/stories/Components.css, and fill it with the following contents.

.input-component {
  display: flex;
  flex-direction: column;
  margin-bottom: 1rem;
}

.input-component span {
  display: block;
  margin-bottom: 0.5rem;
}

.input-component.input-component--large input {
  font-size: 1.2rem;
  padding: 0.5rem 1rem;
}

.select-component {
  display: flex;
  flex-direction: column;
  margin-bottom: 1rem;
}

.select-component span {
  display: block;
  margin-bottom: 0.5rem;
}

.select-component.select-component--large select {
  font-size: 1.2rem;
  padding: 0.5rem 1rem;
}

.tabs-component .tabs-row {
  font-family: 'Nunito Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif;
  display: flex;
}

.tabs-component .tabs-row .tab {
  border: 1px solid #EEEEEE;
  border-bottom: none;
  border-top-right-radius: 4px;
  border-top-left-radius: 4px;
  padding: 0.5rem 1rem;
  cursor: pointer;
}

.tabs-component .tabs-row .tab.active {
  background-color: #EEEEEE;
  cursor: auto;
}

.tabs-component .tabs-content {
  border: 1px solid #EEEEEE;
  padding: 0.5rem 1rem;
}

With this, the components are usable as React components in your application. But you also want them to be browsable through Storybook. For this, you will need to create one file for each component. Start by creating a file src/stories/Input.stories.jsx and enter the following code in it.

import React from 'react';

import { Input } from './Components';

export default {
  title: 'Components/Input',
  component: Input,
};

const Template = (args) => <Input {...args} />;

export const Normal = Template.bind({});

Normal.args = {
  label: 'Normal Input',
  placeholder: 'Enter your value',
  size: 'normal'
};

export const Large = Template.bind({});

Large.args = {
  label: 'Large Input',
  placeholder: 'Enter your value',
  size: 'large'
};

export const Number = Template.bind({});

Number.args = {
  label: 'Integer Number',
  placeholder: 'Enter your value',
  size: 'large',
  type: 'number'
};

export const FloatingPoint = Template.bind({});

FloatingPoint.args = {
  label: 'Floating Point Number',
  placeholder: 'Enter your value',
  size: 'large',
  type: 'floating-point'
};

The export default at the top of the file tells Storybook what the component's name is and which React component the stories in this file refer to. The subsequent exports Normal, Large, Number, and FloatingPoint represent individual stories or use cases for that component. Each story defines a member args that specifies the properties to pass to the component. Creating stories in this way is quick, so now create the next one for the Select component. Create a file src/stories/Select.stories.jsx and paste the following contents into it.

import React from 'react';

import { Select } from './Components';

export default {
  title: 'Components/Select',
  component: Select,
};

const Template = (args) => <Select {...args} />;

export const Default = Template.bind({});

Default.args = {
  size: 'medium',
  label: 'Select an Option',
  options: [
    { value: 'a', description: 'Option A' },
    { value: 'b', description: 'Option B' },
    { value: 'c', description: 'Option C' },
  ]
};

export const Large = Template.bind({});

Large.args = {
  size: 'large',
  label: 'Select an Option',
  options: [
    { value: 'a', description: 'Option A' },
    { value: 'b', description: 'Option B' },
    { value: 'c', description: 'Option C' },
  ]
};

This file defines two stories for the Select component. One story shows it in normal size, and the other shows it in a large size. Finally, do the same for the Tabs component. Create a file src/stories/Tabs.stories.jsx and fill it with the contents below.

import React from 'react';

import { Tabs } from './Components';

export default {
  title: 'Components/Tabs',
  component: Tabs,
};

const Template = (args) => <Tabs {...args} />;

export const Default = Template.bind({});

Default.args = {
  children: [
    <div label="One">Content One</div>,
    <div label="Two">Content Two</div>,
    <div label="Three">Content Three</div>,
  ]
};

Now, you are ready to test out your new components in Storybook. If you haven't done so already, open the terminal in the project folder and run the following command.

npm run storybook

The command runs the Storybook app and opens a browser tab (http://localhost:6006). You can browse the components in the left sidebar. The stories you just created can be found under the Components header, and when you select, for example, the Input -> Number story, you should see something like shown in the image below.

The component shows up in the main view, and the icons above let you change the background, the screen size, and even allow you to check the dimensions of the component's layout. Below the main view, you can manually adjust the options passed to the component. I invite you to play around with all the features Storybook provides.

Creating the unit converter application using Storybook component stories

I will use the convert-units library to implement the unit conversion app. Open a second terminal in your project folder and run the command below.

npm install -E convert-units@2.3.4

Now, in your IDE, create a new file, src/stories/Converter.jsx, and fill it with the contents below.

import React, { useState } from 'react';
import PropTypes from 'prop-types';
import * as convert from 'convert-units';
import { Input, Select } from './Components';

export const Converter = ({measure}) => {
  const possibilities = convert().possibilities(measure).map((unit) => {
      const descr = convert().describe(unit);
      return {
          value: descr.abbr,
          description: `${descr.singular} (${descr.abbr})`
      };
  });

  const [fromUnit, setFromUnit] = useState(possibilities[0].value);
  const [toUnit, setToUnit] = useState(possibilities[0].value);
  const [fromValue, setFromValue] = useState(1);
  const [toValue, setToValue] = useState(convert(1).from(fromUnit).to(toUnit));

  const updateFromUnit = (event) => {
    setFromUnit(() => event.target.value);
    setToValue(() => convert(fromValue).from(event.target.value).to(toUnit));
  };

  const updateToUnit = (event) => {
    setToUnit(() => event.target.value);
    setToValue(() => convert(fromValue).from(fromUnit).to(event.target.value));
  };

  const updateValue = (event) => {
    setFromValue(() => event.target.value);
    setToValue(() => convert(event.target.value).from(fromUnit).to(toUnit));
  };

  return <div className="converter">
      <Select label="From:" options={possibilities} onChange={updateFromUnit}></Select>
      <Select label="To:" options={possibilities} onChange={updateToUnit}></Select>
      <Input label="Value:" type="floating-point" onChange={updateValue}></Input>
      <p>{fromValue} {fromUnit} = {toValue} {toUnit}</p>
  </div>
};

Converter.propTypes = {
  measure: PropTypes.string.isRequired
};

Input.defaultProps = {
  measure: 'length'
};

The component takes a single property called measure, which specifies the type of units to be converted and can be something like mass or length. The code for this component then consists of four parts. The first action is to query the convert-units library for all the possible unit conversion options. Units are mapped into an array of objects, ready to use with the Select component. In the next part, you'll define four state properties, followed by three event handlers. These will react to a change in the user input and update the state accordingly. These event handlers contain the actual calls to the convert-units library where the unit conversion happens. Finally, the component is put together from all the parts and returned. You can also create a story for this more complex component with the individual components. Create a file src/stories/Converter.stories.jsx and paste in the following contents.

import React from 'react';
import { Converter } from './Converter';

export default {
  title: 'Components/Converter',
  component: Converter,
};

const Template = (args) => <Converter {...args} />;

export const Default = Template.bind({});

Default.args = {
  measure: 'length'
};

export const Mass = Template.bind({});

Mass.args = {
  measure: 'mass'
};

When you installed Storybook with the npx sb command, the initialization script added a few components as examples to demonstrate Storybook's capabilities. You will be reusing two of these components for the unit-conversion app.
Open src/stories/Header.jsx and replace its contents with the following code.

import React from 'react';
import PropTypes from 'prop-types';
import { Button } from './Button';
import './header.css';

export const Header = ({ user, onLogin, onLogout }) => (
  <header>
    <div className="wrapper">
      <div>
        <h1>Unit Converter</h1>
      </div>
      {user ? <div> Hello {user.given_name} </div> : ""}
      <div>
        {user ? (
          <Button size="small" onClick={onLogout} label="Log out" />
        ) : (
          <>
            <Button size="small" onClick={onLogin} label="Log in" />
          </>
        )}
      </div>
    </div>
  </header>
);

Header.propTypes = {
  user: PropTypes.shape({}),
  onLogin: PropTypes.func.isRequired,
  onLogout: PropTypes.func.isRequired,
  onCreateAccount: PropTypes.func.isRequired,
};

Header.defaultProps = {
  user: null,
};

I have modified the header component to show the correct application name and allow some structured user data to be passed in. In the story for the header, in file src/stories/Header.stories.jsx, modify the arguments passed to the LoggedIn story to reflect this change.

LoggedIn.args = {
  user: {
    given_name: "Username"
  },
};

Now, open src/stories/Page.jsx and modify its contents to match the code below.

import React from 'react';
import PropTypes from 'prop-types';
import { Header } from './Header';
import './page.css';
import { Tabs } from './Components';
import { Converter } from './Converter';

export const Page = ({useAuth}) => {
  const [user, login, logout] = useAuth();
  return <article>
    <Header user={user} onLogin={login} onLogout={logout} />
    <section>
      <Tabs>
        <Converter measure="length" label="Length" key="length"></Converter>
        <Converter measure="mass" label="Mass" key="mass"></Converter>
        <Converter measure="volume" label="Volume" key="volume"></Converter>
      </Tabs>
    </section>
  </article>;
}

Page.propTypes = {
  useAuth: PropTypes.func.isRequired
};

Page.defaultProps = {
};

This component displays the application page, including the header and a tabbed container that allows switching between Converter components configured to convert different measures. The page needs a useAuth hook passed in that returns the user information and callbacks to log the user in or out. In the stories for the page, in src/stories/Page.stories.jsx, you need to create a mock function that supplies fake user data. Edit the contents of this file to look like the following code.

import React from 'react';
import { Page } from './Page';

export default {
  title: 'Pages/Page',
  component: Page,
};

const mockUseAuth = (loggedIn) => () => [
  loggedIn ? {given_name: "Username"} : undefined, 
  () => {}, 
  () => {}
];

const Template = (args) => <Page useAuth={mockUseAuth(true)} {...args}/>;

export const LoggedIn = Template.bind({});
LoggedIn.args = {
  useAuth: mockUseAuth(true),
};

LoggedIn.parameters = {
  controls: { hideNoControlsWarning: true },
};

export const LoggedOut = Template.bind({});
LoggedOut.args = {
  useAuth: mockUseAuth(false),
};

LoggedOut.parameters = {
  controls: { hideNoControlsWarning: true },
};

Note how mockUseAuth uses currying to return a function that can be used as the useAuth hook in the Page component. You can now use Storybook again to test the Converter component and the full application page. If it's not still running, run npm run storybook again. You can navigate to Pages -> Page in the left sidebar, and you should see something like the image below.

Adding authentication with Okta to the application

You have created a page that uses an useAuth hook to manage user authentication. For the Storybook stories, you made a mock implementation of this hook. This section will show you how to implement the hook using Okta's authentication service. First, register the application with Okta.

Use http://localhost:3000/callback for the Redirect URI and set the Logout Redirect URI to http://localhost:3000.

What does the Okta CLI do?
The Okta CLI will create an OIDC Single-Page App in your Okta Org. It will add the redirect URIs you specified and grant access to the Everyone group. It will also add a trusted origin for http://localhost:3000. You will see output like the following when it’s finished:

Okta application configuration:
Issuer:    https://dev-133337.okta.com/oauth2/default
Client ID: 0oab8eb55Kb9jdMIr5d6

NOTE: You can also use the Okta Admin Console to create your app. See Create a React App for more information.

Next, install the necessary libraries. Open the terminal and run the command below.

npm install -E @okta/okta-react@6.4.1 @okta/okta-auth-js@5.10.0 react-dom@17.0.2 react-router-dom@5.3.0

Open the file src/index.js and modify its contents to match the code below.

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import { App } from './App';
import { Page } from './stories/Page';
import reportWebVitals from './reportWebVitals';
import { BrowserRouter as Router, Route, useHistory } from 'react-router-dom';
import { LoginCallback, SecureRoute, Security } from '@okta/okta-react';
import { OktaAuth, toRelativeUrl } from '@okta/okta-auth-js';
import { useAuth } from './auth';

const oktaAuth = new OktaAuth({
  issuer: 'https://{yourOktaDomain}/oauth2/default',
  clientId: '{clientID}',
  redirectUri: `/callback`,
});

function SecuredRoutes(props) {
  const history = useHistory();
  const restoreOriginalUri = async (_oktaAuth, originalUri) => {
    history.replace(toRelativeUrl(originalUri || '/', window.location.origin));
  };

  return (
    <Security oktaAuth={oktaAuth} restoreOriginalUri={restoreOriginalUri}>
      <Route path="/" exact render={(props) => <App {...props} useAuth={useAuth}/>} />
      <SecureRoute path="/converter" exact render={(props) => <Page {...props} useAuth={useAuth}/>} />
      <Route path="/callback" component={LoginCallback} />
    </Security>
  );
}

ReactDOM.render(
  <React.StrictMode>
    <Router>
      <SecuredRoutes />
    </Router>
  </React.StrictMode>,
  document.getElementById('root')
);

reportWebVitals();

Here {yourClientID} is the client ID that you obtained earlier and {yourOktaDomain} is your Okta domain. This change does several things. The oktaAuth instance provides a global authentication singleton. The main render function now contains a Router element that allows the application to navigate different routes. Finally, SecuredRoutes is a component that wraps the routes in a Security component. This component makes a useOktaAuth hook available for all components contained within it. Inside this component, you define the routes. Note how you pass a useAuth hook into the App and the Page components. Create a new file src/auth.js and add the following code to implement this hook.

import { useEffect, useState } from 'react';
import { useOktaAuth } from '@okta/okta-react';

export const useAuth = () => {
  const { oktaAuth, authState } = useOktaAuth();
  const [user, setUser] = useState(null);

  useEffect(() => {
    if (authState?.isAuthenticated) {
      if (!user) {
        oktaAuth.getUser().then(setUser);
      }
    } else {
      setUser(null);
    }
  }, [authState, user, oktaAuth]);

  const login = async () => oktaAuth.signInWithRedirect('/');
  const logout = async () => oktaAuth.signOut('/');

  return [user, login, logout];
};

Finally, you need to modify the existing App component to use the authentication hook. Open src/App.js and adjust the content to look like this.

import './App.css';
import { Link } from 'react-router-dom';
import { Header } from './stories/Header';

export const App = ({useAuth}) => {
  const [user, login, logout] = useAuth();

  return (
    <div className="App">
      <Header user={user} onLogin={login} onLogout={logout} />
      <h1>Unit Converter</h1>
      <p>
      <Link to="/converter">Go to the app!</Link>
      </p>
    </div>
  );
}

Congratulations, you have completed your React application with Storybook. You can now open the console in the project folder and run the following command to start the app.

npm start

You should see the application's front page in your browser. When you click the Go to the app! link, you'll log in on the Okta page. After successfully signing in, you will redirect to the unit converter page, which looks like the image below.

Learn more about React, Storybook, and Single-Page Apps

In this tutorial, I have shown you how to create a React application and use Storybook to browse the application's components. Storybook is a great tool that can enhance your development workflow.

It lets you view and test your components in isolation.
You can specify the location of each component in a hierarchical menu and then browse through the components in your browser.
You can have multiple stories showcasing different use cases for each component.
You can also modify the component parameters and see the impact on the visual appearance in real time.
Storybook can keep running during the development process, and it will reflect any changes you make to your code.

The application you wrote was a simple unit-conversion app. I guided you on using the convert-units library to convert length, mass, and volume. You assembled the individual components to create a larger component containing multiple input elements. I have shown you how Storybook lets you create stories, test these complex components, and complete application pages.

If you want to learn more about any of these topics, please follow the links below.

You can find the code for this tutorial on GitHub.

oktadev / okta-react-storybook-example

A React application using Storybook

If you liked this tutorial, chances are you like others we publish. Please follow @oktadev on Twitter and subscribe to our YouTube channel to get notified when we publish new developer tutorials.

Original post written by Holger Schmitz for the Okta Developer blog.

Kotlin: A Beginner's Guide and Tutorial

OktaDev — Thu, 12 Dec 2019 05:00:00 +0000

Kotlin is a modern, statically typed language within the JVM. Kotlin is a cross-platform, multi-purpose, free and open-source language developed by JetBrains under the Apache 2.0 license and has constructs for both Object Oriented and Functional programming styles, which can be mixed. It can be used for web development, server and client, and mobile development, using most Java IDEs.

Kotlin is an awesome option for Java developers because it is concise, expressive, and safe. According to JetBrains estimates, it can cut the total lines of code in your app by up to 40 percent. Kotlin also helps prevent NullPointerExceptions as it provides non-nullable types.

According to GitHub Octoverse Report 2018, Kotlin is the number one fastest-growing language. With 2.2M users, its popularity increases every month, and big companies are using it. Android and JVM developers are falling in love with its features. Let’s learn why.

In this post you will find:

An overview of Kotlin’s features
A guide for building a “Hello, World!” app and solving a basic algorithm problem
A quick step by step for running a Kotlin Spring Boot application with authentication via Okta

In order to complete the full tutorial, you’ll need the following tools:

Java 8
Apache Maven
IntelliJ (or another IDE)

Before we dive into the tutorial, let’s talk a little about why Kotlin might be the right choice for your next project.

Kotlin vs. Java, aka Why this Tutorial?

Kotlin was designed to fix a number of Java’s issues:

Null references: Java allows null reference values, and as seen above, Kotlin type system helps to eliminate the access to a member of a null reference, which would result in the equivalent of a NullPointerException.

Invariant array: In Java, arrays are covariant, and array Integer[] is a subtype of Number[], so the compiler allows assigning a Double to a Number[] reference, but the program might raise an exception at runtime if the instance is Integer[]. Kotlin does not let you assign Array<String> to Array<Any>, preventing runtime failures. Any is the root of the Kotlin class hierarchy.

// Compiles but will raise java.lang.ArrayStoreException
Integer[] intArray = new Integer[1];
Number[] numberArray = intArray;
numberArray = intArray;
numberArray[0] = 1.0;

In Kotlin:

var intArray = arrayOf(1)
var numArray = arrayOf(1.0)
numArray = intArray // Compiler error Type mismatch

Any is the root of the Kotlin class hierarchy, but it is not equivalent to Object. However, java.lang.Object is mapped to kotlin.Any!, and the ! notation means it can be Any or Any? (nullable or not). As Object, other Java types are not used “as is”, but mapped to Kotlin types. A complete list of mappings is available in the Kotlin Reference.

No raw types: There are no raw types in Kotlin, as generics are different. Java raw types, for example List, is converted into star projections List<*>!, which are similar to raw types, but provide runtime safety. How? The compiler will not allow write operations if the type argument is unknown, as it might cause a cast exception when reading. In Java, you can add any object to a raw List, but in Kotlin adding to a start projected list won’t compile.

Use-site variance: Java’s type system uses bounded wildcards to increase API flexibility, as generic types are invariant (as opposed to Java arrays, which are covariant), meaning List<String> is not a subtype of List<Object>, but can be assigned to List<? extends Object> type. In Kotlin, instead of bounded wildcards, use-site variance allows to restrict the generic type in the place it is used, with a simpler syntax like Array<out Any>, equivalent to Java’s Array<? extends Object>. The compiler verifies the parameter type is only returned from a method of the instance, but not consumed, to avoid runtime exceptions, for example, if attempting to write a String to Array<Int>.

package com.okta.developer

fun main() {
    val a = arrayOf("uno", "dos", "tres")
    readMethod(a)
}

fun readMethod(a: Array<out Any>) {
    println(a[0])
    a.set(0, 1) // Out-projected type prohibits the use of fun set
}

The example above does not compile in Kotlin, because the readMethod() receives the out-projected array (only read operations allowed) and it is calling the write operation set().

No checked exceptions: Java checked exceptions must be somehow handled for the program to compile, and are many times swallowed by an empty catch block. Kotlin does not have checked exceptions, because it is suggested that in large software projects it decreases productivity.

Proper function types: As opposed to Java SAM (Single Abstract Method) conversions, where a lambda expression is convertible to a SAM type according to some rules, Kotlin uses a family of function types like (Int) -> String, with the special notation corresponding to the signature of the functions (parameters and return values).

A complete list of Kotlin features, not supported in Java, is available at Kotlin Reference.

Java and Kotlin Interoperability

Kotlin is 100% interoperable with Java, Kotlin code can be called from Java and vice versa.Existing Java code can be used with some considerations, for example, Java getters and setters are represented by properties in Kotlin:

val calendar = Calendar.getInstance()
calendar.firstDayOfWeek = Calendar.MONDAY // setFirstOfWeek()

With an IDE like IntelliJ IDEA, you can add Java source code to a Kotlin project just by creating a .java file.

Objects coming from Java, called platform types, have relaxed null-checks for practical reasons, and safety is the same as in Java. Kotlin will not inform a compilation error, but the call might fail at runtime. For example, if Kotlin calls Java code that returns an ArrayList, the inferred type in Kotlin will be ArrayList<String!>!, which means the collection can be nullable, and the items as well.

In the Java code below, null is added as an item to the list.

import java.util.ArrayList;

public class ArrayWithNulls {

    public static ArrayList<String> create(){
        ArrayList<String> strings = new ArrayList();
        strings.add(null);
        strings.add("foo");
        return strings;
    }
}

In the Kotlin lines below, we are calling the previous Java code, so the safety is relaxed. The program compiles, but as the first item is null, it will fail at runtime with IllegalStateException.

val list = ArrayWithNulls.create()
val item = list.get(0) // platform type inferred (ordinary Java object)
item.substring(1) // IllegalStateException: item must not be null

Pre-Tutorial: A Taste of Kotlin

To avoid the programmer’s curse, let’s not skip trying a simple “Hello, World!” example with Kotlin. An easy way to get started with Kotlin is to download and install IntelliJ IDEA Community Edition from JetBrains, which is also free. And also, install Maven for dependency management and to run the application from the command line.

Start IntelliJ IDEA and create a new Kotlin project, choosing Kotlin/JVM.

Set the project name, location, and Java 8 SDK. After the project is created, add Maven support by doing a right-click on the project and choosing Add Framework Support. Then select the Maven checkbox and click OK.

Rename src/main/java to src/main/kotlin and src/test/java to src/test/kotlin.

Add a new Kotlin File/Class to the src/main/kotlin folder. Set the file name to app. The IDE will automatically add the extension .kt, which indicates it is a Kotlin file. Add the following code:

package com.okta.developers

fun main() {
    println("Hello, World!")
}

In the lines above, you can see a package declaration, which is optional. If not present, everything goes to the default package. The main function is the entry point to the application and can be declared without parameters (if your program does not need to accept command line arguments) and return nothing. The println function is part of the Kotlin Standard Library and prints the message and the line separator to the standard output stream.

NOTE: In Kotlin, it is not required to match directories and packages. Source files can be placed arbitrarily in the file system, and one file can contain multiple classes. For pure Kotlin projects, the common root package com.okta.developers is omitted in the filesystem.

Edit your pom.xml to add Kotlin dependencies and the Kotlin Maven Plugin.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.okta.developers</groupId>
    <artifactId>kotlin-hello-world</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <kotlin.version>1.3.50</kotlin.version>
        <junit.version>4.12</junit.version>
        <main.class>com.okta.developer.AppKt</main.class>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-stdlib</artifactId>
            <version>${kotlin.version}</version>
        </dependency>
        <dependency>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-test-junit</artifactId>
            <version>${kotlin.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>${junit.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <sourceDirectory>${project.basedir}/src/main/kotlin</sourceDirectory>
        <testSourceDirectory>${project.basedir}/src/test/kotlin</testSourceDirectory>
        <plugins>
            <plugin>
                <groupId>org.jetbrains.kotlin</groupId>
                <artifactId>kotlin-maven-plugin</artifactId>
                <version>${kotlin.version}</version>

                <executions>
                    <execution>
                        <id>compile</id>
                        <goals>
                            <goal>compile</goal>
                        </goals>
                    </execution>

                    <execution>
                        <id>test-compile</id>
                        <goals>
                            <goal>test-compile</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>2.6</version>
                <configuration>
                    <archive>
                        <manifest>
                            <addClasspath>true</addClasspath>
                            <mainClass>${main.class}</mainClass>
                        </manifest>
                    </archive>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>1.2.1</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>java</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <mainClass>${main.class}</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Build and run application with the following Maven command:

mvn package exec:java

It should output the hello message:

Hello, World!
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

Kotlin Idioms

Now, let’s apply some Kotlin idioms to solve a common interview problem: finding anagrams in substrings. Given a string, find the number of pairs of substrings that are anagrams of each other.

First, update the main function in app.kt to make it scan the string to analyze from the standard input:

package com.okta.developers

fun main() {
    val string = readLine()
    val result = string?.let { Anagrams().count(it) }

    println(result)
}

In the code above, we declare two immutable variables, using the keyword val. Mutable variables must be declared with the keyword var. Kotlin also does type inference, so as you can see, none of the variables declare type. readLine() is a function from the kotlin-stdlib that reads a line from the standard input stream, available for JVM and Native targets.

Then, add a new Kotlin File/Class to the existing project with the name Anagrams in src/main/kotlin. Extend String to add a function that returns a String with the same characters in lexicographic order, appending the following code to Anagrams.kt:

package com.okta.developer

fun String.sort(): List<Char> = this.toList().sorted()

The Extension functions idiom provides a mechanism to extend a class without using inheritance, allowing to write new functions for classes in third party libraries that cannot be modified, even if they are final classes. In the code above, we declare the function sort() as an extension for the String class, with no parameters and return type List<Char>.The sort() function is a Single-expression function, another Kotlin idiom for writing shorter code, as the return keyword and enclosing brackets are not required.

Below the sort(), define the Anagrams class as follows:

class Anagrams {

    fun count(s: String): Int {
        var count = 0
        for (i in 1 until s.length) {
            var substrings = s.windowed(i, 1)
                .map { it.sort() }
                .toMutableList()
            while (substrings.isNotEmpty()) {
                val substring = substrings.removeAt(0)
                count += substrings.count{ it == substring }
            }
        }
        return count
    }
}

The for loop in count(s: String) function will iterate over i in a half-open range, from 1 to s.length, not including s.length. That way, in each iteration using the windowed function of String, we create all the possible substrings of the current length i. Then sort() all the substrings and create a MutableList, to be able to remove elements later. Each collection type in the Kotlin Standard Library (set, list, map) provides a read-only and a mutable interface that defines write operations.

As the substrings are sorted, they can be compared to each other to find anagrams. Using the List function count() and passing a lambda predicate expressed with the it parameter, the number of matches will be returned. Many times, a lambda expression has only one parameter, and the implicit name of a single parameter it allows a shorter syntax.

Add the following test cases for the Anagram class in a new Kotlin file src/test/kotlin/AnagramsTest.kt:

package com.okta.developers

import org.junit.Test
import kotlin.test.assertEquals

class AnagramsTest {

    val anagrams = Anagrams()

    @Test
    fun `given abba count returns 4`(){
        assertEquals(4, anagrams.count("abba"))
    }

    @Test
    fun `given ifailuhkqq count returns 3`(){
        assertEquals(3, anagrams.count("ifailuhkqq"))
    }
}

Run the test cases with Maven:

mvn test

The test results will show in the console:

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running com.okta.developer.AnagramsTest
Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.083 sec

Results :

Tests run: 2, Failures: 0, Errors: 0, Skipped: 0

Run the program the same way as before, type the string to analyze in the console, then type the enter key. You should see an output like the following:

[INFO] --- exec-maven-plugin:1.2.1:java (default) @ kotlin-hello-world ---
abba
4
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

Tutorial: Use Kotlin With Spring Boot Securely

Finally, let’s see how easy is to create a Kotlin Spring Boot application with Okta OpenID Connect (OIDC) authentication.

Using the Spring Initializr API, create a Maven project with the following command:

curl https://start.spring.io/starter.zip -d dependencies=web,okta \
-d language=kotlin \
-d type=maven-project \
-d groupId=com.okta.developer \
-d artifactId=kotlin-spring-boot \
-d name="Kotlin Spring Boot" \
-d description="Demo project of a Kotlin Spring Boot application" \
-d packageName=com.okta.developer \
-o kotlin-spring-boot.zip

Unzip the file:

unzip kotlin-spring-boot.zip -d kotlin-spring-boot
cd kotlin-spring-boot

Secure your Application with OpenID Connect

If you already have an Okta account, see the Create a Web Application in Okta sidebar below. Otherwise, we created a Maven plugin that configures a free Okta developer account + an OIDC app (in under a minute!).

./mvnw com.okta:okta-maven-plugin:setup

You should see the following output:

First name: Jimena
Last name: Garbarino
Email address: ***
Company: ***
Creating new Okta Organization, this may take a minute:
OrgUrl: https://dev-123456.okta.com
Check your email address to verify your account.

Writing Okta SDK config to: /home/indiepopart/.okta/okta.yaml

Configuring a new OIDC, almost done:
Created OIDC application, client-id: ***

Check your email and follow the instructions to activate your Okta account.

If you already have an Okta Developer account

Log in and create a new Application:

From the Applications page, choose Add Application.

On the Create New Application page, select Web.

Give your app a memorable name, add http://localhost:8080/login/oauth2/code/okta as a Login redirect URI.

Copy the issuer (found under API > Authorization Servers ), client ID, and client secret into src/main/resources/application.properties.
okta.oauth2.issuer=$issuer
okta.oauth2.client-id=$clientId
okta.oauth2.client-secret=$clientSecret

Edit KotlinSpringBootApplication located in the package com.okta.developer to add a controller mapping that will print a welcome message in the browser window.

package com.okta.developer

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.security.core.annotation.AuthenticationPrincipal
import org.springframework.security.oauth2.client.authentication.OAuth2AuthenticationToken
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RestController

@SpringBootApplication
@RestController
class KotlinSpringBootApplication {

    @GetMapping("/")
    fun hello(@AuthenticationPrincipal authenticationToken: OAuth2AuthenticationToken): String {
        return "Welcome ${authenticationToken.principal.attributes["name"]}"
    }
}

fun main(args: Array<String>) {
    runApplication<KotlinSpringBootApplication>(*args)
}

As you can see, in the hello() function, the authenticated user is passed in the authenticationToken. The @AuthenticationPrincipal annotation from Spring Security helps to resolve the principal to the expected principal type. The welcome message is built using String interpolation, a Kotlin idiom for variable substitution inside strings.

Run the application with the following command:

./mvnw spring-boot:run

Browse to http://localhost:8080 and the application should start an OAuth 2.0 authentication code flow, redirecting to the Okta login page.

After the login, you should see the welcome message:

Welcome, Jimena Garbarino

You now have a secure application with just a few lines of Kotlin and the help of Spring Boot!

Learn More about Kotlin, Java, and Secure Authentication with these Tutorials

I hope this blog post helped you grasp how succinct and expressive Kotlin is and why developers are loving it. You can find all the tutorial code in repositories kotlin-hello-world and kotlin-spring-boot on GitHub. To learn more about Kotlin, check out the following links:

Questions? Requests for a future post? Drop them in the comments! And don’t forget to follow @oktadev on Twitter and subscribe to our YouTube channel.

Original post written by Jimena Garbarino for the Okta Developer blog.

OAuth 2.0 Java Guide: Secure Your App in 5 Minutes

OktaDev — Wed, 27 Nov 2019 17:53:51 +0000

Modern applications rely on user authentication, but it can present Java developers with a difficult challenge, as well as a range of framework-specific options to choose from. We have seen many Spring developers start with a simple, home-grown authentication service they plan to replace “later” with a more robust option… only for that homegrown service to bikeshed its way to a permanent place in the stack. To end this cycle of heartbreak, this post will show how simple it is to implement an enterprise-grade auth service, even in a simple app.

In this tutorial, you’ll create an application that displays user information. You’ll configure it manually first to see its drawbacks. Then, we’ll use a more professional approach. By the end of this tutorial, you’ll have a Spring-based Java application that uses OAuth 2.0 to authenticate users, and it will take you 5 minutes to make these changes!

Create Your Java Application with Spring

Let’s start by creating the project structure. You’ll use Spring Initializer to create the application. Go to start.spring.io and fill in the following information:

Project: Maven Project
Language: Java
Group: com.okta.authorizationapp
Artifact: oauth
Dependencies:
- Spring Web
- Spring Security
- Thymeleaf

You can also generate the project from the command line. Paste the following command in your terminal to download the project with the same configuration as above:

curl https://start.spring.io/starter.zip \
        -d dependencies=web,thymeleaf,security \
        -d packageName=com.okta.authorizationapp \
        -d name=authorization-app \
        -d type=maven-project \
        -o java-authorization-app.zip

That’s it! Now your Java project structure is created, and you can start developing your app.

Build User Security on Your Own

This tutorial will use Maven, but you can easily do it using Gradle if you prefer.

First, import the project in your favorite IDE/editor. Right now, your project has only one class, AuthorizationAppApplication that bootstraps the application. When you run this class, the server starts, and you can go to your browser to see the results.

However, you first need a page to access, so let’s create a home page.

Inside src/main/java/com/okta/authorizationapp/controller/ create the class HomeController:

@Controller
public class HomeController {

    private Map<String, LocalDateTime> usersLastAccess = new HashMap<>();

    @GetMapping("/")
    public String getCurrentUser(@AuthenticationPrincipal User user, Model model) {
        String username = user.getUsername();

        model.addAttribute("username", username);
        model.addAttribute("lastAccess", usersLastAccess.get(username));

        usersLastAccess.put(username, LocalDateTime.now());

        return "home";
    }
}

This class defines a controller for the / path. When you access your app without defining any other path, this code will execute.

The controller’s first important action retrieves the current user’s information. Since you annotated your user attribute with AuthenticationPrincipal, Spring Security will automatically retrieve this information.

The controller also receives a model parameter that stores the data used to render the page. Right now, this data is the username and the last time the user accessed your application.

Create Dynamic Messages on User Login

The final step is to update the user’s last access date and define which HTML template should render the request. In your case, the endpoint is called home. Spring will search for a home.html file inside the src/main/resources/templates folder.

You don’t have this file yet, so let’s go there and create it:

<html>
  <head>
    <title>Java OAuth 2.0 Tutorial - Homepage</title>
  </head>
  <body>
    <h1 th:text="'Welcome, ' + ${username} + '!'"></h1>
    <ul>
      <li th:if="${lastAccess}" th:text="'Last access: ' + $"></li>
    </ul>
  </body>
</html>

This is an HTML file altered slightly by Thymeleaf, one of the libraries you imported when you created the project. Thymeleaf receives the model object from the server and renders the values from it in HTML. Just type ${variable} to refer to a variable in the model object.

The th:text attribute will let you define a dynamic text in the HTML element. Here, we use it to display a dynamic greeting, and the last time the user accessed the application.

The first time a user accesses your app, there is no prior access recorded. To make sure you’re not presenting a meaningless field, use th:if. If the field is null, the li tag is not rendered, and the user won’t see it.

Add Basic Login to Your Java Spring App

Now you have the endpoint, you just need to add security to your app.

Inside src/main/javacom/okta/authorizationapp/configuration/ create the class SecurityConfiguration:

@EnableWebSecurity
public class SecurityConfiguration extends WebSecurityConfigurerAdapter {

    private PasswordEncoder passwordEncoder = new BCryptPasswordEncoder();

    @Override
    protected void configure(AuthenticationManagerBuilder auth) throws Exception {
        auth.inMemoryAuthentication()
                .passwordEncoder(passwordEncoder())
                .withUser("john.doe")
                .password(passwordEncoder().encode("secret"))
                .roles("USER");
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return passwordEncoder;
    }
}

This class will ensure that users must log in to access your application. Right now there is only one user named john.doe who can log into the app.

Run the application by calling the main method inside AuthorizationAppApplication. You can also run it from the command line. Inside the project folder, run the following command:

mvn spring-boot:run

When you go to http://localhost:8080 you should see the following login page:

Type john.doe and secret as username and password. You should be redirected to the home page. On the first visit, only Welcome, john.doe! will display. From the second visit, you should also see the last access:

You now have an application that manages security. Good job!

There is a big problem, though… Right now, you can only login with one user. Even worse, the user information is hardcoded in your app. To simplify user access and security, you can use Okta to manage your authentication. It will provide you a very simple way to integrate with OAuth 2.0 in less than 5 minutes. Let’s configure OAuth 2.0 in your sample app to see how easy it is. Let’s start by creating an Okta account.

Create an Okta Account

If you don’t have an Okta account, go ahead and create one. Once you have signed up, go through the following steps:

Login in to your account
Click on Applications > Add Application

You will Fokbe redirected to the following page:

Select Web and click Next

Fill in the following options in the form:

Name: hello-world
Base URIs: http://localhost:8080
Login redirect URLs: http://localhost:8080/login/oauth2/code/okta
Grant Type allowed:
- Client Credentials
- Authorization Code
Click Done.

Now you can use your Okta application to authenticate users to your app.

Use OAuth 2.0: A Fast, Professional Approach

Let’s start by adding Okta’s library to your project.

Go to the pom.xml and add Okta’s Spring Boot starter:

<dependency>
    <groupId>com.okta.spring</groupId>
    <artifactId>okta-spring-boot-starter</artifactId>
    <version>1.3.0</version>
</dependency>

Okta will manage your app authentication, so you can delete the SecurityConfiguration class.

Inside HomeController, make the following changes:

@GetMapping("/")
public String getCurrentUser(@AuthenticationPrincipal OidcUser user, Model model) {
    String email = user.getEmail();

    model.addAttribute("email", email);
    model.addAttribute("lastAccess", usersLastAccess.get(email));
    model.addAttribute("firstName", user.getGivenName());
    model.addAttribute("lastName", user.getFamilyName());

    usersLastAccess.put(email, LocalDateTime.now());

    return "home";
}

Your endpoint will now receive an OidcUser compatible with OAuth 2.0. This class provides much more user information than you had before, so you can modify your HTML to display it. Replace username with email, and add firstName, and lastName, which are fields you didn’t have before. To do this, go to the hello.html and make the following changes:

<body>
  <h1 th:text="'Welcome, ' + ${email} + '!'"></h1>
  <ul>
    <li th:if="${lastAccess}" th:text="'Last access: ' + $"></li>
    <li th:if="${firstName}" th:text="'First name: ' + $"></li>
    <li th:if="${lastName}" th:text="'Last name: ' + $"></li>
  </ul>
</body>

You are still greeting the user as before, but you’re also displaying the new information from the endpoint. You have made all the code changes and now just need to add some configurations. Create an okta.env file in the root directory of your app with the following environment variables.

export OKTA_OAUTH2_ISSUER=/oauth2/default
export OKTA_OAUTH2_CLIENT_ID={CLIENT_ID}
export OKTA_OAUTH2_CLIENT_SECRET={CLIENT_SECRET}

You will find {CLIENT_ID} and {CLIENT_SECRET} in the application’s page from the Okta dashboard. To access it, follow the steps below:

In your Okta dashboard, go to Applications
Select the hello-world application
Click on the General tab

You should see both values in the Client Credentials area. Your {yourOktaDomain} will be visible in your Okta dashboard, just click on Dashboard in the menu. You will see the Org URL in the right upper corner.

Once you’ve pasted these values into okta.env, run the following commands to start your app.

source okta.env
mvn spring-boot:run

That’s it!

Log Into Your Spring App With OAuth 2.0 Enabled

Navigate to http://localhost:8080. Your app will redirect you to Okta’s login page:

After logging in, you’ll be redirected to your application and see a message like this:

You’ve done it! In 5 minutes you added OAuth 2.0 in your application with very little configuration along the way.

Learn More About Spring Security, Spring Boot and Java Authentication

If you want to take a look at the completed source code, you can access it on GitHub.

Do you want to read more about OAuth 2.0 and Java in general? You might be interested in the following articles:

For more articles like this one, follow @oktadev on Twitter. We also regularly publish screencasts to our YouTube channel.

Build a Simple Microservice with C# Azure Functions

OktaDev — Wed, 13 Nov 2019 05:00:00 +0000

I’ve always liked microservices because they embrace small, well-encapsulated building blocks. They mitigate deployment hell by treating each component of a software system as its own product, with versions, testing, and releases.

A microservice is “micro” because of the narrow scope of its functionality, not necessarily because the length of its code is very short. A microservice’s functionality, so long as it’s kept to the limited scope, can go as deep as required by the business. By limiting the scope, we isolate different bits of logic in our software by vertical niche; our client application can still get to all the functionality it needs, through several small APIs, each of which scales independently. Much better than a single, monolithic API!

Prerequisites for C# Azure Functions

In this article, we’ll build an authentication microservice that will receive a username and password, and determine whether those credentials are valid. You will need the following for this tutorial:

You can find the complete working source code for this article on Github.

Create Your C# Azure Function in Visual Studio

Let’s start up a .NET project in Visual Studio, so you have a full-featured IDE (integrated development environment). Depending on what you want your Azure Function to do and your maintenance needs, you could opt to use the function editor inside the Azure portal.

Open up Visual Studio and create a new project. In the New Project wizard, select Azure Function as the type of project. Name your project AuthService and click Create.

On the next screen, select Azure Functions v1 (.NET Framework) from the drop-down at the top, then choose Http trigger as the trigger for your new project. Finally, change the access rights to Anonymous and click OK to create your new Azure Function project.

Your new project can be deployed as an Azure Function, and in the following sections, you’ll add some custom code to your new project.

Add C# Data Transfer Objects to Your Azure Function

These types will feed data in and out of the Azure Function. Add a class to your project named User.cs. This class holds data about the logged-in user. Paste the following code into the new file:

using System;

namespace AuthService
{
  public class User
  {
    public string Id { get; set; }
    public DateTime PasswordChanged { get; set; }
    public string Login { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Locale { get; set; }
    public string TimeZone { get; set; }
  }
}

Add a class to your project named Session.cs. This class is similar to the User class we just created but holds data related to the user’s active session. Paste the following code into the new file:

using System;

namespace AuthService
{
  public class Session
  {
    public string Token { get; set; }
    public string ExpiresAt { get; set; }
  }
}

Add a class to your project named AuthResponse.cs. This class will be used to return the result of the login operation back to the client. It includes information about the success or failure of the login attempt, and will also provide information about the user and session - if the login was successful. Paste the following code into the new file:

using System;

namespace AuthService
{
  public class AuthResponse
  {
    public bool WasSuccessful { get; set; }
    public string Message { get; set; }

    public Session Session { get; set; }
    public User User { get; set; }
  }
}

Add one more new class named OktaAuthenticationRequest.cs. This class holds the data to send to Okta with the authentication request. Paste the following code into the new file:

using System;

namespace AuthService
{
  public class OktaAuthenticationRequest
  {
    public string username { get; set; }
    public string password { get; set; }
  }
}

Create Your C# Azure Function

Install the Newtonsoft.Json package, as shown in the image below. The latest version of the package at the time this article was published is 12.0.2.

Next, add the following statements to the top of Function1.cs.

using System.Text;
using System.Net.Http.Headers;
using Newtonsoft.Json;

In this next step, overwrite the code for the Run() method of Function1. Copy the code below and paste it into your Function1.cs file. Be sure to completely replace the existing code there.

[FunctionName("Function1")]
public static async Task<HttpResponseMessage> Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]HttpRequestMessage req, TraceWriter log)
{
  var OktaDomain = "{yourOktaDomain}";
  var OktaApiToken = "{yourApiToken}";
  Session session = null;
  User user = null;

  //get username
  string publicKey = req.GetQueryNameValuePairs()
    .FirstOrDefault(q => string.Compare(q.Key, "user", true) == 0)
    .Value;

  if (publicKey == null)
    req.CreateResponse<AuthResponse>(new AuthResponse() { WasSuccessful = false, Message = "Must pass `user` as a query string parameter" });

  //get password
  string privateKey = req.GetQueryNameValuePairs()
    .FirstOrDefault(q => string.Compare(q.Key, "password", true) == 0)
    .Value;

  if (privateKey == null)
    req.CreateResponse<AuthResponse>(new AuthResponse() { WasSuccessful = false, Message = "Must pass `password` as a query string parameter" });

  //TODO

  //response
  var wasSuccess = session != null && user != null;
  return req.CreateResponse<AuthResponse>(new AuthResponse()
  {
    WasSuccessful = wasSuccess,
    Message = wasSuccess ? "Success" : "Invalid username and password",
    Session = session,
    User = user
  });
}

This is the meat of the function to authenticate the provided credentials. It first retrieves the user and password input from the HTTP request and validates that both were provided. TODO will be replaced with our authentication code in the next step.

At the end of the function, the response is an instance of AuthResponse that sets WasSuccessful to true when the session and user variables are not null. Based on that evaluation, it will also set Message to either “Success” or “Invalid username and password”.

Set Up Your Okta Account

Next, you’ll need a free Okta Developer account.

You’ll also need to generate an API token for your account. To keep them secure, API tokens are only displayed once when they’re first generated, so make sure you copy it and keep it safe so that we can use it again later. To generate your API token, log in to your Okta Developer account. Once logged in, click API in the main menu, then go to Tokens. When you’re on the Tokens screen, click Create Token near the top of the page. You’ll have to provide a public name for your token, then click Create Token.

Your API token should then display on the screen. Copy the value so that you can use it in the next step.

Set Your API Token

Once you’ve generated your API token, go back to the first two lines of the function we copied earlier. Those first lines define values for your OktaDomain and your OktaApiToken, so replace those values with the settings for your Okta account:

var OktaDomain = "{yourOktaDomain}";
var OktaApiToken = "{yourApiToken}";

Add Your Okta Authentication Code

Now that we have your Okta domain and API token, we are ready to write the code to authenticate users with Okta.

The code below sends your API token, along with the user-provided username and password to the Okta service as a JSON encoded string. It then receives a JSON encoded response (responseJson) with the results from the login attempt. The response is then decoded and stored in the object responseObj where we check the data inside. If the login was a success, the response will also provide data about the user and the user’s session.

Replace the TODO in Function1.cs with the following code:

//generate URL for service call using your configured Okta Domain
string url = string.Format("{0}/api/v1/authn", OktaDomain);

//build the package we're going to send to Okta
var data = new OktaAuthenticationRequest() { username = publicKey, password = privateKey };

//serialize input as json
var json = new StringContent(JsonConvert.SerializeObject(data), Encoding.UTF8, "application/json");

//create HttpClient to communicate with Okta's web service
using (HttpClient client = new HttpClient())
{
  //Set the API key
  client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("SSWS", OktaApiToken);

  //Post the json data to Okta's web service
  using (HttpResponseMessage res = await client.PostAsync(url, json))

  //Get the response from the server
  using (HttpContent content = res.Content)
  {
    //get json string from the response
    var responseJson = await content.ReadAsStringAsync();

    //deserialize json into complex object
    dynamic responseObj = JsonConvert.DeserializeObject(responseJson);

    //determine if the returned status is success
    if (responseObj.status == "SUCCESS")
    {
      //get session data
      session = new Session()
      {
        Token = responseObj.sessionToken,
        ExpiresAt = responseObj.expiresAt
      };

      //get user data
      user = new User()
      {
        Id = responseObj._embedded.user.id,
        Login = responseObj._embedded.user.login,
        Locale = responseObj._embedded.user.locale,
        TimeZone = responseObj._embedded.user.timeZone,
        FirstName = responseObj._embedded.user.firstName,
        LastName = responseObj._embedded.user.lastName
      };
    }
  }
}

This code creates a new OktaAuthenticationRequest; and posts that instance, serialized as JSON, to a URL that uses your Okta domain (in the URL) and your Okta API token (in the Authentication header).

OktaAuthenticationRequest then decodes the JSON results and stores (successful) user data in instances of the Session and User DTOs you created. These variables determine whether the operation was a success.

Run Your Azure Function Locally

To run your Azure Function locally, just hit the run button in Visual Studio.

A console window will appear with the Azure Function logo at the top. Just below the logo, on the 2nd printed line, the console will display the URL that the app is listening to. (In the screenshot below, the URL is http://localhost:7071.) Copy the URL.

Modify the URL to execute your Azure Function by adding /api/Function1 to the end. Your new URL should look something like this:

http://localhost:7071/api/Function1

Open up Postman and paste your modified URL as the request URL. Select “POST” as the HTTP request method. Then add user and password as keys for two query parameters, and set their values to your actual username and password. These are the credentials that your C# Azure Function will authenticate to execute your Azure Function when the HTTP request is executed.

Click Send to execute the HTTP request.

If the credentials you provided were incorrect, then the value for WasSuccessful will be false, and the Message will contain a value stating, “Invalid username or password”.

Publish to Azure

Inside Visual Studio, right-click on your AuthService project and select Publish. In the publish wizard, select Create New app service.

On the next screen, provide a name for your new app service. I have left mine as the default name here. Click Publish when you’re ready to create your service.

It will take a moment for Visual Studio to create your new app service. Once finished, it will show a tab with a URL to your new app service. Click on the URL to open it up in a browser.

Modify the URL in the same way we did your local URL to call your function. Replace the URL in Postman with your new URL and leave the user and password query params as they are. Click Send to execute your deployed C# Azure Function.

You now have a working authentication service!

Learn More About ASP.NET, Azure Functions, and Microservices

If you’re interested in learning more about Azure Functions and microservices check out the following links:

If you have any questions about the post, feel free to leave me a comment below. Don’t forget to follow us on Twitter, Facebook, and YouTube so you never miss any of our killer content!

Get Started with the ELK Stack

OktaDev — Thu, 26 Sep 2019 05:00:00 +0000

Good design principles require that microservices architectures are observable, and provide a centralized monitoring tool. This tool allows development teams to verify the overall system health, inspect logs and errors, and get feedback after deployments. So what is the Elastic (or ELK) Stack and why it is an excellent option to meet this need?

In this tutorial post, you will learn how to …

Set up and run the ELK stack in Docker containers
Set up JHipster Console to monitor microservices infrastructure
Create a microservices architecture with JHipster
Enable monitoring with JHipster Console
Configure OpenID Connect authentication for microservices

The Evolution of the Elastic Stack

The acronym ELK stands for Elasticsearch, Logstash, and Kibana, three open-source projects that form a powerful stack for log ingestion and visualization, log search, event analysis, and helpful visual metrics for monitoring applications.

E lasticsearch is the heart of the stack: a JSON-based search and analytics engine, distributed and scalable. It was built on top of Apache Lucene and provides a JSON REST API, cluster management, high availability, and fault tolerance.

L ogstash is an ETL (extract, transform, load) tool to enrich documents, run data processing pipelines. These pipelines ingest data from multiple sources, transform and send it to Elasticsearch.

K ibana provides the visualization front-end, a window into the Elastic Stack. With dashboards and visualization elements, the data stored in Elasticsearch can be explored, aggregated and analyzed.

From version 7 on, the ELK Stack was renamed to Elastic Stack and added Beats to the stack. Beats is a family of lightweight data shippers that work with Elasticsearch and Logstash.

Set up the Elastic Stack

Elastic has published a Docker Compose configuration, to demonstrate the stack components on a single machine. Install Docker and Docker Compose and follow these steps to start up the stack:

Windows users must configure 2 environment variables, check out the instructions on the stack-docker github repository.

Allow at least 4GB of RAM for the containers, also check out instructions for your environment.

Clone the stack-docker repository

 git clone https://github.com/elastic/stack-docker.git

Setup the stack with Docker Compose

 cd stack-docker
 docker-compose -f setup.yml up

When the setup completes, it will output the password for the elastic user. On a slow connection, this can take up to 20 minutes. When it completes, you will see the following logs:

 setup_1 | Setup completed successfully. To start the stack please run:
 setup_1 | docker-compose up -d
 setup_1 |
 setup_1 | If you wish to remove the setup containers please run:
 setup_1 | docker-compose -f docker-compose.yml -f docker-compose.setup.yml down --remove-orphans
 setup_1 |
 setup_1 | You will have to re-start the stack after removing setup containers.
 setup_1 |
 setup_1 | Your 'elastic' user password is: Z8GFVXu9UVsBrM6nup5fHw==
 stack-docker_setup_1 exited with code 0

Launch the stack

Start the stack in the foreground to watch the containers logs:

 docker-compose up

When you see Kibana log the response to health check requests sent by the Beats family and you see at least one heartbeat entry in the logs, you can try the login:

 kibana | {"type":"response","@timestamp":"2019-09-23T20:38:47Z","tags":[],"pid":1,"method":"get","statusCode":200,"req":{"url":"/login?next=%2F","method":"get","headers":{"host":"kibana:5601","user-agent":"Go-http-client/1.1","referer":"http://kibana:5601"},"remoteAddress":"172.25.0.9","userAgent":"172.25.0.9","referer":"http://kibana:5601"},"res":{"statusCode":200,"responseTime":30,"contentLength":9},"message":"GET /login?next=%2F 200 30ms - 9.0B"}
 ...
 heartbeat | 2019-09-23T20:38:52.213Z   INFO    [monitoring]    log/log.go:144  Non-zero metrics in the last 30s    {"monitoring": {"metrics": {"beat":{"cpu":{"system":{"ticks":160,"time":{"ms":50}},"total":{"ticks":430,"time":{"ms":120},"value":430},"user":{"ticks":270,"time":{"ms":70}}},"handles":{"limit":{"hard":1048576,"soft":1048576},"open":9},"info":{"ephemeral_id":"d8d4f6a2-39fa-41cb-9e9c-520438d49a9e","uptime":{"ms":93132}},"memstats":{"gc_next":4194304,"memory_alloc":3365792,"memory_total":12191384,"rss":327680}},"libbeat":{"config":{"module":{"running":0}},"output":{"events":{"acked":24,"batches":6,"total":24},"read":{"bytes":5970},"write":{"bytes":16878}},"pipeline":{"clients":4,"events":{"active":0,"published":24,"total":24},"queue":{"acked":24}}},"system":{"load":{"1":4.83,"15":2.43,"5":3.44,"norm":{"1":1.2075,"15":0.6075,"5":0.86}}}}}}

You may notice exceptions in the log output. For this demonstration, they can be safely ignored. If you run into any issues with docker, you can start fresh with:
docker container ls -a | cut -c1-12 | xargs docker container rm --force
docker images | cut -c69-80 | xargs docker rmi
docker system prune -a
NOTE: This will destroy all docker containers, images and networks, so use at your own risk.

Go to http://localhost:5601 to log into Kibana.

Once you log in (using the elastic user and the password you captured above), explore the installed dashboards from the Dashboards section via the menu on the left. Heartbeat is one of the Beat services that monitors your services uptime from a provided list of URLs. Open the dashboard Heartbeat HTTP monitoring and see the power of the stack for data visualization.

The JHipster Console

The Jhipster Console, an awesome monitoring solution based on the Elastic Stack, allows the visualization and analysis of JHipster application metrics over time. The Console provides pre-configured dashboards to monitor microservices infrastructure. You can review the complete list of features in JHipster Console’s documentation.

One of the easier ways to start with the JHipster Console is to deploy the applications and enable monitoring with the docker-compose sub-generator. You’ll use this to:

Create a microservices architecture with JHipster
Enable monitoring with JHipster Console
Configure OpenID Connect for authentication to microservices

Create a Java Microservices Architecture with JHipster

To install a version of JHipster that will work here, you need to install Node.js.

Install JHipster

npm install -g generator-jhipster@6.3.1
jhipster --version

The version command should output something like this:

INFO! Using JHipster version installed globally
6.3.1

Create a directory for the project:

mkdir jhipster
cd jhipster

Create apps.jh to define store, blog, and gateway microservices in JHipster Domain Language (JDL). We are going to recreate a Java-based example of microservices architecture we have built before for this tutorial.

application {
  config {
    baseName gateway,
    packageName com.okta.developer.gateway,
    applicationType gateway,
    authenticationType oauth2,
    prodDatabaseType postgresql,
    serviceDiscoveryType eureka,
    testFrameworks [protractor]
  }
  entities Blog, Post, Tag, Product
}

application {
  config {
    baseName blog,
    packageName com.okta.developer.blog,
    applicationType microservice,
    authenticationType oauth2,
    prodDatabaseType postgresql,
    serverPort 8081,
    serviceDiscoveryType eureka
  }
  entities Blog, Post, Tag
}

application {
  config {
    baseName store,
    packageName com.okta.developer.store,
    applicationType microservice,
    authenticationType oauth2,
    databaseType mongodb,
    devDatabaseType mongodb,
    prodDatabaseType mongodb,
    enableHibernateCache false,
    serverPort 8082,
    serviceDiscoveryType eureka
  }
  entities Product
}

entity Blog {
  name String required minlength(3),
  handle String required minlength(2)
}

entity Post {
  title String required,
  content TextBlob required,
  date Instant required
}

entity Tag {
  name String required minlength(2)
}

entity Product {
  title String required,
  price BigDecimal required min(0),
  image ImageBlob
}

relationship ManyToOne {
  Blog{user(login)} to User,
  Post{blog(name)} to Blog
}

relationship ManyToMany {
  Post{tag(name)} to Tag{post}
}

paginate Post, Tag with infinite-scroll
paginate Product with pagination

microservice Product with store
microservice Blog, Post, Tag with blog

Now, in your jhipster folder, run the import-jdl generator.

jhipster import-jdl apps.jh

Deploy Monitoring using `docker-compose`

In the project folder, create a subfolder for the docker-compose configuration and run the sub-generator.

mkdir docker-compose
cd docker-compose
jhipster docker-compose

The generator will ask you to define the following configurations:

Type of application: Microservices application
Type of gateway: JHipster based on Zuul
Which applications to include: blog, gateway, store
If the database is clustered: no
if monitoring must be enabled: yes, with JHipster console
Additional technologies for monitoring: Zipkin
Password for JHipster Registry: default

When the generator has almost finished, a warning shows in the output:

WARNING! Docker Compose configuration generated, but no Jib cache found
If you forgot to generate the Docker image for this application, please run:
To generate the missing Docker image(s), please run:
  ./mvnw package -Pprod verify jib:dockerBuild in /home/indiepopart/jhipster/blog
  ./mvnw package -Pprod verify jib:dockerBuild in /home/indiepopart/jhipster/gateway
  ./mvnw package -Pprod verify jib:dockerBuild in /home/indiepopart/jhipster/store

You can follow the instructions above for creating the microservices images, or create an aggregator pom.xml and use just one command for building all the images, as described in our post on Java microservices.

Setup Okta OpenID Connect (OIDC) Authentication for Your Microservices

By default, the microservices architecture authenticates against Keycloak. Update the settings to use Okta as the authentication provider:

First of all, go to Okta for a free developer account.

Once you log in, click Your Org, and it will take you to the Developer Console. Go to the Applications section and add a new Web Application. Set the following authentication settings:

Name: give a name for your application
Base URIs: http://localhost:8761 and http://localhost:8080
Login redirect URIs: http://localhost:8080/login/oauth2/code/oidc and http://localhost:8761/login/oauth2/code/oidc
Grant Type Allowed: Authorization Code and Refresh Token

For simplicity, this tutorial only creates Web App, and its credentials will be used for all the services. In a real environment, each service must identify itself with its own credentials, and you should create one Web App or Service for each one of them in the Okta console.

Copy the Client ID and Client secret, as we will use it for the application’s setup. Find the Org URL at the top right corner in the Okta Dashboard.

Create a docker-compose/.env file with the following content:

OIDC_CLIENT_ID=<client_id>
OIDC_CLIENT_SECRET=<client_secret>
RESOURCE_ISSUER_URI=<org_url>/oauth2/default

Edit docker-compose/docker-compose.yml and update the SECURITY_* settings for the services blog-app, gateway-app, and store-app:

SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_OIDC_ISSUER_URI=${RESOURCE_ISSUER_URI}
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}

The same authentication must be set up for the JHipster Registry. Edit docker-compose/jhipster-registry.yml and set the same values as the environment section of the gateway-app.

JHipster applications require the specific user roles ROLE_USER and ROLE_ADMIN as claims in the ID Token. In the Okta Developer Console, go to Users > Groups and create a group for each JHipster role, and add users to each group.

Now go to API > Authorization Servers, select the default server and Add Claim with the following settings:

Name: groups
Include in token type: ID Token, Always
Value type: Groups
Filter: Matches regex, set the Regex to .*

Enable Debug Logs and Zipkin

To send debug logs to the JHipster Console, let’s update the log level in the prod profile. Edit src/main/resources/config/application-prod.yml to set the level for each service (blog-app, store-app, and gateway-app) to DEBUG for the com.okta.developer.* logger. For example, in the blog’s application-prod.yml:

logging:
    level:
        com.okta.developer.blog: DEBUG

Also, for each service, update the LoggingAspectConfiguration to load when the prod profile is active. Change the @Profile annotation:

@Configuration
@EnableAspectJAutoProxy
public class LoggingAspectConfiguration {

    @Bean
    @Profile({JHipsterConstants.SPRING_PROFILE_DEVELOPMENT, JHipsterConstants.SPRING_PROFILE_PRODUCTION})
    public LoggingAspect loggingAspect(Environment env) {
        return new LoggingAspect(env);
    }
}

Zipkin is a distributed tracing system that helps to troubleshoot latency issues in microservices architectures. With a traceId propagated from service to service, calls to different services can be correlated and analyzed as a part of the same flow. The Zipkin server and UI are provided with the JHipster Console, and JHipster apps can integrate with Zipkin through Spring Cloud Sleuth. To enable Zipkin tracing, add the zipkin profile to blog-app, gateway-app, and store-app in docker-compose/docker-compose.yml.

- SPRING_PROFILES_ACTIVE=prod,swagger,zipkin

You also need to rebuild the Docker images with the zipkin profile, for blog-app, store-app, and gateway-app with the following Maven command:

./mvnw package -Pprod -Pzipkin verify jib:dockerBuild -DskipTests

ProTip: If you’re on a system with bash shell, like Linux or MacOs, you can do this from the jhipster folder to build each project at once:
for i in blog gateway store
do 
cd $i 
./mvnw package -Pprod -Pzipkin verify jib:dockerBuild -DskipTests
cd ..
done

Run the Monitored Microservices Architecture

Are you ready for the best? Go to the docker-compose folder and start the services with the following command:

docker-compose up

You will see a huge amount of logging while each service starts.

jhipster-registry_1 | ----------------------------------------------------------
jhipster-registry_1 | Application 'jhipster-registry' is running! Access URLs:
jhipster-registry_1 | Local: http://localhost:8761
jhipster-registry_1 | External: http://172.20.0.2:8761
jhipster-registry_1 | Profile(s): [composite, dev, swagger, oauth2]
jhipster-registry_1 | ----------------------------------------------------------

Log into the JHipster Registry at http://localhost:8761 with Okta user credentials and check the service’s health.

Once all the services are up, log in to the gateway application and create some blogs and posts to generate traffic. To do this, use the Entities menu at the top left of the application. The gateway home is at http://localhost:8080.

The fun part! Access the JHipster Console at http://localhost:5601. Go to the Dashboards section, and open the requests-dashboard. You should see some nice curves:

Since you integrated the JHipster Console with Zipkin UI, in the traces-dashboard, you can find the longest traces duration on the left. If you click on a traceId on the right, it will open the trace in the UI and you will be able to examine the flow.

Learn More About JHipster and Elastic Stack

I hope you enjoyed this tutorial and the power of the Elastic Stack and the JHipster Console for monitoring a microservices architecture. To continue expanding your knowledge on JHipster monitoring and Okta integration with the Elastic Stack, check out the following links:

If you liked this post, chances are you’ll like our other posts on JHipster and microservices:

To be notified when we published new posts, follow @oktadev on Twitter. We also publish screencasts to our YouTube channel on a regular basis.

Simple Authentication with Spring Security

OktaDev — Fri, 31 May 2019 05:00:00 +0000

Authentication is vital to all but the most basic web applications. Who is making the request, wanting data, or wanting to update or delete data? Can you be sure that the request is coming from the stated user or agent? Answering this question with certainty is hard in today’s computer security environment. Fortunately, there is absolutely no reason to reinvent the wheel.

Spring Boot with Spring Security is a powerful combination for web application development. With relatively few lines of code, you can implement a variety of authentication systems. These systems are tested, updated, and implemented according to specifications by experts.

In this tutorial, you are going to build a very simple Spring Boot app that starts with basic-auth and progresses through form-based authentication, custom form-based authentication, and OAuth 2.0 / OpenID Connect using Okta as the OAuth provider. We will also look at SAML auth. The Spring Security SAML implementation, however, is currently in transition and not updated to the most current version of Spring Boot.

This tutorial looks specifically at authentication, leaving authorization for another day. Authentication answers the question: who is making the request. Authorization comes after authentication and answers the question: is the authenticated user allowed to make the specific request?

Requirements and Assumptions for Authentication with Spring Security

This tutorial assumes a basic familiarity with Java and Spring Boot. The project utilizes the Gradle build system (because I find Groovy DSL endlessly preferable to XML). You do not need Gradle installed, however, since all projects include the Gradle wrapper.

You do not need a comprehensive understanding of OAuth 2.0 and OpenID Connect (OIDC) - thankfully, because it’s complex, detailed, and sprawling at times. I’m still working to understand many aspects of it. However, a basic understanding would be helpful. If you want to go deeper, there are some links at the end of the article that can help you.

Very (very) briefly, OAuth 2.0 is the second major version of Open Authorization, an open-source authorization specification. From the OAuth spec committee: “OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices.” Notice two things: 1) it’s authorization only, so no authentication; and 2) it’s a specification, so there’s no implementation. OIDC builds on top of OAuth 2.0 to add an identity layer (authentication) using a well-defined token.

Spring Security Authentication with Okta

Okta is an identity access and management company that provides a whole host of software-as-service identity products. We have an implementation of OAuth 2.0 and OpenID Connect that makes adding single sign-on (SSO) to a Spring Boot app easy.

Our API enables you to:

Authenticate and authorize your users
Store data about your users
Perform password-based and social login
Secure your application with multi-factor authentication
And much more! Check out our product documentation for more information

Register for a forever-free developer account, and when you’re done, come back to learn more about building authentication with Spring Boot and Spring Security.

Other than that, you need a computer and a web browser. And if you didn’t have those, well, how would you be here?

Download the Spring Security Example Apps

Go ahead and download the example apps from this tutorial’s GitHub repository.

git clone https://github.com/oktadeveloper/okta-spring-security-authentication-example.git

In the project, you will see three directories:

basic-auth
form-auth
okta-oauth

Dive Into Basic Authentication with Spring Security

Basic authentication is by far the easiest method. Unfortunately, it was designed for simpler times on the internet. It’s not really functional for professional applications. I’ve used it for in-house tools on occasion when I needed something simple and quick to keep casual surfers off of a page. However, basic auth sends a users credentials in essentially plain text (base64 encoded) in the HTTP authentication header. Thus basic auth should always be combined with SSL to protect the user credentials. Basic auth also uses a browser-generated popup panel for retrieving the user credentials. The panel cannot be styled or customized.

First, take a look at the build.gradle file.

plugins {  
  id 'org.springframework.boot' version '2.1.5.RELEASE'  
  id 'java'  
}  

apply plugin: 'io.spring.dependency-management'  

group = 'com.okta.springsecurityauth'  
version = '0.0.1-SNAPSHOT'  
sourceCompatibility = '1.8'  

repositories {  
  mavenCentral()  
}  

dependencies {  
  implementation 'org.springframework.boot:spring-boot-starter-security'  
  implementation 'org.springframework.boot:spring-boot-starter-web'  
  testImplementation 'org.springframework.boot:spring-boot-starter-test'  
  testImplementation 'org.springframework.security:spring-security-test'  
}

This line sets the Spring Boot version:

id 'org.springframework.boot' version '2.1.5.RELEASE'

These are the two dependencies that include Spring Security and Spring MVC.

implementation 'org.springframework.boot:spring-boot-starter-security'  
implementation 'org.springframework.boot:spring-boot-starter-web'

The rest is pretty much boilerplate.

Here is the main application file (src/main/java/com/okta/springsecurityauth/Application.java).

package com.okta.springsecurityauth;  

import org.springframework.boot.SpringApplication;  
import org.springframework.boot.autoconfigure.SpringBootApplication;  

@SpringBootApplication  
public class Application {  

    public static void main(String[] args) {  
        SpringApplication.run(Application.class, args);  
    }
}

This is the entry point for the Java application. The main thing to note is how little is there. The @SpringBootApplication annotation tells Spring to bootstrap in all of the Spring Boot goodness.

Next take a look at the WebController, src/main/java/com/okta/springsecurityauth/WebController.java.

package com.okta.springsecurityauth;  

import org.springframework.stereotype.Controller;  
import org.springframework.web.bind.annotation.RequestMapping;  
import org.springframework.web.bind.annotation.ResponseBody;  

@Controller  
public class WebController {  

    @RequestMapping("/")
    @ResponseBody
    public String index() {
        return "Welcome home!";
    }
}

The web controller file has a little more action. This is where the only HTTP endpoint of the project is defined. This file defines a simple home controller that returns a text string.

The @Controller annotation tells Spring that the file is defining web controller endpoints. The @RequestMapping annotation defines the mapping between the HTTP requests and the controller methods. And the @ResponseBody annotation tells Spring that the method is going to return the request body directly as a String, as opposed to returning the name of a template file.

The last file is where all of the security is defined. Cleverly it’s named SecurityConfiguration.java.

Take a look, src/main/java/com/okta/springsecurityauth/SecurityConfiguration.java

package com.okta.springsecurityauth;  

import org.springframework.context.annotation.Configuration;  
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;  
import org.springframework.security.config.annotation.web.builders.HttpSecurity;  
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;  

@Configuration  
public class SecurityConfiguration extends WebSecurityConfigurerAdapter {  

    @Override  
    public void configure(HttpSecurity http) throws Exception {  
        http  
            .authorizeRequests()  
            .anyRequest().authenticated()  
            .and()  
            .httpBasic();  
    }  

    @Override  
    protected void configure(AuthenticationManagerBuilder auth) throws Exception {  
        auth.inMemoryAuthentication()  
            .withUser("user")  
            .password("{noop}pass") // Spring Security 5 requires specifying the password storage format  
            .roles("USER");  
    }  

}

You can see how little configuration is required. In the first method, the fluent API is used with the HttpSecurity object to configure Spring Security: security is activated, all requests are authenticated, and HTTP basic is used.

The second method is really just a bit of a hack for this tutorial. It configures an in-memory authentication manager and creates a user with credentials user:pass.

Let’s give it a try! From a terminal, go to the root directory of the project.

Run the project using: ./gradlew bootRun.

Navigate to http://localhost:8080.

You’ll see the browser-generated login form. Enter the credentials user and pass. You’ll see the wonderful success page that says, “Welcome home!”

Step-up To Form-Based Authentication with Spring Security

HTTP Basic authentication is about as simple as it gets and really isn’t all that useful in the real world. Form-based authentication is a lot more realistic. Open the /form-auth folder in your IDE.

The build.gradle file is the same. So are the Application.java and the WebController.java files. The only significant change is in the SecurityConfiguration.java file (and in this file, only one line has changed).

src/main/java/com/okta/springsecurityauth/SecurityConfiguration.java:

package com.okta.springsecurityauth;  

... 

@Configuration  
public class SecurityConfiguration extends WebSecurityConfigurerAdapter {  

    @Override  
    public void configure(HttpSecurity http) throws Exception {  
        http  
            .authorizeRequests()  
            .anyRequest().authenticated()  
            .and()  
            .formLogin(); // <-- this was changed
    }  

    ...
}

See how ridiculously simple Spring is making things for us. All you had to do was change the httpBasic() fluent method to formLogin() and Spring Boot automatically generates a login form for you.

Run it using ./gradlew bootRun.

You’ll see the auto-generated Spring Boot login form.

But what if you want to style your own custom form instead of using the Spring-generated one? It’s not much more work.

First, add the Thymeleaf dependency to your build.gradle file:

dependencies {  
  ...
  implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'  
  ...
}

Update the WebController.java file with two new controller methods:

package com.okta.springsecurityauth;  

import org.springframework.stereotype.Controller;  
import org.springframework.ui.Model;  
import org.springframework.web.bind.annotation.RequestMapping;  
import org.springframework.web.bind.annotation.ResponseBody;  

@Controller  
public class WebController {  

    @RequestMapping("/")  
    @ResponseBody  
    public String index() {  
        return "You made it!";  
    }  

    @RequestMapping("/login.html")  
    public String login() {  
        return "login.html";  
    }  

    @RequestMapping("/login-error.html")  
    public String loginError(Model model) {  
        model.addAttribute("loginError", true);  
        return "login.html";  
    }  

}

Notice that the /login-error.html path uses the same template as the /login.html path, but adds a loginError attribute to the Model. This is simply a way of handling errors.

Also, notice that the new controller methods do not have the @ResponseBody annotation. This, combined with the new Thymeleaf dependency, means that these methods are returning the name of the template to be rendered (as opposed to the raw response). The templates are assumed by default to be in the src/main/resources/templates folder.

Add a new file: src/main/resources/templates/login.html:

<!DOCTYPE html>  
<html xmlns:th="http://www.thymeleaf.org">  
<head>  
    <title>Login page</title>  
    <style>  
        #container {  
            padding-top:50px;  
            width:400px;  
            margin: 0 auto;  
            font-size:1.5rem;  
        }  
        input {  
            width: 100%;  
            display:block;  
            padding: 5px;  
            font-size: 1.1rem;  
            box-sizing: border-box;  
        }  
        label {  
            margin-top:10px;  
            display:block;  
        }  
        #submit, #submit:focus {  
            margin-top: 20px;  
            border-radius: 8px;  
            padding: 10px;  
            color: white;  
            background-color: #2084ba;  
            border: none;  
        }  
        .error {  
            color: white;  
            background-color: indianred;  
            opacity: 0.7;  
            padding: 10px;  
            width: 100%;  
            text-align: center;  
            box-sizing: border-box;  
            border-radius: 8px;  
        }  
    </style>  
</head>  
<body>  
<div id="container">  
    <h2>Login page</h2>  
    <form th:action="@{/login.html}" method="post">  
        <label for="username">User</label>  
        <input type="text" id="username" name="username" autofocus="autofocus" />  
        <label for="password">Pass</label>  
        <input type="password" id="password" name="password" />  
        <input id="submit" type="submit" value="Log in" />  
    </form>  
    <p th:if="${loginError}" class="error">There was a problem logging you in</p>  
</div>  
</body>  
</html>

This is the Thymeleaf template file used for the login page. Thymeleaf is the standard templating system used with Spring Boot. It’s a fully-featured templating system with tons of features. Check out the project website for more info.

The last change you need to make is to update the configure(HttpSecurity http) method in the SecurityController.java file:

package com.okta.springsecurityauth;  

...  

@Configuration  
public class SecurityConfiguration extends WebSecurityConfigurerAdapter {  

    @Override  
    public void configure(HttpSecurity http) throws Exception {  
        http  
            .authorizeRequests()  
            .anyRequest().authenticated()  
            .and()  
            .formLogin()  
            .loginPage("/login.html")  
            .failureUrl("/login-error.html")  
            .permitAll();  
    }  

...  
}

These three lines were added:

.loginPage("/login.html")  
.failureUrl("/login-error.html")  
.permitAll();

They define the custom login endpoint, the login error endpoint, and instruct Spring Security to permit all requests to those endpoints.

Run the app again using ./gradlew bootRun.

This time you’ll see the custom login form.

It’s (almost) SAML Time!

The Spring Security SAML extension is currently in flux. There are some unofficial 2.x releases that work, but they’re not officially supported.

From the Spring Security SAML GitHub page:

This project is being rewritten. There is a base implementation in the develop including milestone releases in the milestone repository.

In the develop-3.0 branch we are creating a solution that builds on top of the milestones and is better aligned with Spring Security. The intent with this branch is to merge it with the Spring Security project and release as part of Spring Security core.

For that reason, we will not be publishing any official releases of the 2.0.0 milestones, but will maintain it until all feature functionality that exists in the milestones are part of Spring Security.

If you want to venture into the current state of Spring Boot SAML, the Spring SAML Extension Docs are a good place to start.

Matt Raible at Okta also has a great tutorial for implementing SAML with Spring Boot 1.x.

Vincenzo De Notari has an example Service Provider implementation using SAML 2.0 and Spring Boot 2.1.3.

NOTE: If you want to test out SAML with Okta, you’ll need to request a trial of Okta’s Enterprise Edition.

Add OAuth 2.0 + OpenID Connect Authentication

Once you’re in the developer.okta.com dashboard, create an OIDC Application:

From top-menu, click on Applications.

Click green Add Applications button.
Click Web application type, and Next.
Give the app a Name. Any name.
Set Login Redirect URIs to http://localhost:8080/login/oauth2/code/okta.
Click Done.

Take note of the Client ID and Client Secret at the bottom of the page. You’ll need these in a bit.

Great! That’s all you have to do to configure Okta as an OIDC provider.

Open the oauth-okta directory from the example repository.

Before you do anything else, you need to update the src/main/resources/application.yml file. You need to fill in three values:

Okta URL, something like https://dev-123456.okta.com/oauth2/default
Client ID (from the OIDC app you just created)
Client Secret (also from the OIDC app you just created)

okta:  
  oauth2:  
    issuer: https://{yourOktaDomain}/oauth2/default  
    client-id: {yourClientID}
    client-secret: {yourClientSecret} 
spring:  
  thymeleaf:  
    cache: false

Next, take a look at the dependencies section of the build.gradle file.

dependencies {  
  implementation 'com.okta.spring:okta-spring-boot-starter:1.2.0'  
  implementation 'org.springframework.boot:spring-boot-starter-web'  

  ...
}

You’ll notice one new dependency as well as no longer needing spring-boot-starter-security:

okta-spring-boot-starter

The Okta Spring Boot Starter is an extension by Okta that simplifies some of the dependency management and configuration associated with OAuth and Spring Security. You can check out the project GitHub page for more info.

The rest of the project, honestly, is beguilingly simple. The Application.java file is the same.

The WebController.java file has a few new methods added. This could actually have been the same as the first couple of examples, simply returning a string, but I thought it would be nice to demonstrate how to access some of the authenticated user information.

package com.okta.springsecurityauth;  

...  

@Controller
public class WebController {

    @RequestMapping("/")
    @ResponseBody
    public String home(@AuthenticationPrincipal OidcUser oidcUser) {
        return "Welcome, " + oidcUser.getFullName();
    }

    @RequestMapping("/attributes")
    @ResponseBody
    public String attributes(@AuthenticationPrincipal OidcUser oidcUser) {
        return oidcUser.getAttributes().toString();
    }

    @RequestMapping("/authorities")
    @ResponseBody
    public String authorities(@AuthenticationPrincipal OidcUser oidcUser) {
        return oidcUser.getAuthorities().toString();
    }

}

The / home endpoint returns a welcome message and the full name of the OIDC user.

The /attributes endpoint returns the user attributes that the app received from Okta.

The /authorities endpoint returns the user authorities (roles and scopes). These have to do with authorization, defining what actions the user is permitted to execute or what resources the user can access and modify.

You’ll notice that there is no SecurityConfiguration.java file. In this simple example, it’s unnecessary because OAuth is the default authentication scheme and by default, all paths require authentication (which is what we want).

Great! Now give it a try. Run the app in the oauth-okta directory using ./gradlew bootRun.

Navigate to http://localhost:8080/.

You may need to use an incognito window or log out of the Okta developer dashboard if you want to see Okta’s hosted login screen.

Welcome, Andrew Hughes

You can also try out the http://localhost:8080/attributes endpoint and the http://localhost:8080/authorities endpoint.

Finish Up Your Spring Boot + Spring Security App with Authentication

In this tutorial, you went through a selection of Spring Boot and Spring Security authentication methods. You started with HTTP basic; moved on to form-based auth with the auto-generated form; and then customized the app to use a Thymeleaf template for the login form. Next, you implemented an OAuth/OIDC single sign-on app using Okta and Spring Boot.

You can find the source code for all the examples in this tutorial on GitHub.

If you’d like to learn more about Spring Boot, Spring Security, or secure authentication, check out any of these great tutorials:

If you want to dive deeper, take a look at the Okta Spring Boot Starter GitHub page.

If you have any questions about this post, please add a comment below. For more awesome content, follow @oktadev on Twitter, like us on Facebook, or subscribe to our YouTube channel.