The Overview Page describes what the Basic SPA Code Sample is trying to achieve, so let’s get it running.
Step 1: Add Domains to your PC
First go to the hosts file on your local PC, which will exist at one of these locations:
|Mac OS / Linux||/etc/hosts|
Add entries as follows to represent our domains:
- 127.0.0.1 web.mycompany.com
- 127.0.0.1 api.mycompany.com
Step 2: Use Okta as an Authorization Server
Next go to https://developer.okta.com and sign up to get a developer account, after which you will receive an email to activate your account.
You will then get your own Authorization Server, which you can log into at an Admin URL such as this: https://dev-843469-admin.oktapreview.com.
Once logged in, browse to API / Authorization Servers and view the default item that has been automatically created:
The above URL is what we will use in our Code Sample, and in my case the value is https://dev-843469.oktapreview.com/oauth2/default.
Step 3: Register OAuth Applications
In Okta we must add trust entries so that our applications can act as OAuth Clients and call the Authorization Server.
First register a Service Application for our API and note that the key OAuth settings are the client_id and client_secret:
Next register a Single Page Application and note that the key OAuth settings are the client_id and the redirect_uri:
HTTP or HTTPS?
No OAuth solution is Production Ready unless it is running over SSL / TLS. However, I will use plain HTTP for Initial UIs and APIs – then switch to a more secure Developer Setup once our SPA sample is complete.
Step 4: Download Code from GitHub
The project is available here, consisting of a UI and API component. It can be downloaded / cloned to your local PC with this command:
- git clone https://github.com/garyarcher36/authguidance.websample1
Step 5: View Code in an IDE
I use Visual Studio Code on Windows, Mac OS and Fedora Linux, since it is cross platform and lightweight.
Select ‘Open Folder’ and browse to the AuthGuidance.WebSample1 folder, to view the code for both UI and API with syntax coloring:
Step 6: Update Configuration
Both the SPA and API have configuration files. In a real world app these would typically be delivered by your Continuous Delivery process.
For the SPA you will need to update the configuration to match your OAuth Server Base URL and Client Id:
For the API you will need to update the configuration to match your OAuth Server Base URL, Client Id and Client Secret:
Step 7: Install Node JS if Required
Go to the Node JS Web Site and run the installer for your operating system.
Step 8: Install SPA and API Dependencies
From both the basicspa and basicapi folders run ‘npm install‘:
Step 9: Start the API
From the basicapi folder run ‘npm start‘ to run the API, which will listen on port 80. If other system components are listening on port 80, such as IIS or Apache, stop them temporarily.
Note that on Windows you may need to use an administrator user and on Mac OS or Linux you will need to run this command:
- sudo -E npm start
Browse to the following URL to get data and verify that you get an Unauthorized response:
In production you would run your API as a low privilege user, and there are various ways to enable this. Our objective though is just to enable real world HTTPS traffic on a developer PC.
Use Alternative Ports if you prefer
My preference is to use Standard Ports for local development, to match those allowed by company firewalls (80 or 443).
If you prefer to use an alternative port such as 3000, change the host names in Okta and the above configuration files:
Step 10: Build the Web UI
From the basicspa folder run ‘npm start‘ to build our ES6 code into an ES5 bundle file that works in all browsers including Internet Explorer:
Step 11: Run the Web UI
In a browser, navigate to a page using this URL, which represents a bookmarked location within our SPA:
Once OK is clicked the SPA does an OAuth redirect to log the user in. You can sign in with your Okta user id and password:
After login an OAuth access token is returned to the UI, which resumes its workflow from the bookmarked location.
The UI now has an access token so can make a cross domain call to the API (api.mycompany.com) to get personalized data for the user in the token.
Step 12: Run a User Session
After login the user will work with the UI until the access token expires, and subsequent operations are much simpler, as can be seen by refreshing the page:
Step 13: Open a New Tab and Access our SPA
Our SPA uses Session Storage so that OAuth tokens are private to each tab. However, the Identity Provider Cookie is shared between all tabs.
This leads to pretty good Multi Tab Browsing Usability, as can be seen if you open a second browser tab for the SPA:
- The SPA in the new tab will not have an access token yet
- The SPA in the new tab will redirect the user to get one
- The user will not be prompted to login again, due to the IDP cookie
- The user Single Signs On to your SPA on the new tab
Where Are We?
Hopefully you have a basic working Web UI and API, but it is focused more on an initial developer setup than anything else.
Essential features are missing and will be implemented in later samples. Next we will drill into some technical details.