On this page
Token inline hook
This guide provides a working example of an Okta token inline hook. It uses the website Glitch.com (opens new window) to act as an external service to receive and respond to token inline hook calls.
Learning outcomes
- Understand the Okta token inline hook calls and responses.
- Implement a simple working example of a token inline hook with a Glitch.com external service.
- Test the token inline hook.
What you need
- Okta Developer Edition organization (opens new window)
- Glitch.com (opens new window) project or account
- A Node.js Express framework sample application. This guide works with the sample application in the Sample code section below.
Sample code
- Okta Token Inline Hook Example (opens new window)
- Express Sample Applications for Okta (opens new window)
About token inline hook implementation
The token inline hook can be used to customize the Authorization Code flow that occurs between an application and the Okta org used for authentication.
This guide provides example code for an external service to respond to calls from a token inline hook, and provides an end-to-end scenario using a local application, an Okta org, and the external service.
The Scenario
In the following token inline hook scenario, the external service code parses a request from Okta, evaluates the user name against a simple patient data store, and, if the user is a patient, responds to Okta with a command to add a patient ID claim to the token. If the user is not part of the data store, no action is taken. The token is returned to the local application for authentication.
At a high-level, the following workflow occurs:
- A user logs into an Okta-Hosted Login sample application.
- The Okta org authenticates the user and mints an authentication token.
- The Okta token inline hook triggers and sends a request to an external service.
- The external service evaluates the request, and if the user is a patient, adds a patient ID claim to the token.
- The authentication token is directed back to the Okta-Hosted Login application where the user is signed in.
Tip: For another in-depth look at a token inline hook implementation, see the following Developer Experience blog example by Micah Silverman, Use Okta Token Hooks to Supercharge OpenID Connect (opens new window).
Set up the sample Express application
The sample Node.js Express application is designed to demonstrate the Authorization Code flow, and includes an Okta-Hosted Login sample used in this token inline hook guide. Access the code from the following Github repository:
Follow the README.md (opens new window) instructions to install and run the Okta-Hosted Login sample application with your Okta org. Make sure to have this application running before proceeding with the token inline hook setup.
Parse the token inline hook request
The external service in this scenario requires code to handle the token inline hook request from the Okta org. Use the Okta Token Inline Hook (opens new window) Glitch example to either build or copy the code (re-mix on Glitch) that parses the token inline hook call.
Note: Make sure to have the required default code and packages in your project. See Common Hook Set-up Steps.
From the token inline hook request, the following code retrieves the value of the user name from the data.identity
object.
Check against the data store
In this scenario, a pre-populated static array of patient names and patient IDs (patients
) is used to simulate a real-world data store. The user name included with the Okta request is checked against this array. If the user name in the request matches a value in the patients
array, the associated patient ID is stored as a variable, patientID
.
Note: Modify this data store to make sure it contains one or more user names that are assigned to your application in your Okta org.
Send a response to Okta
The variable, patientID
, can now be returned to Okta as an additional token claim using the commands
object. For further information on the token commands
object, see the token inline hook reference documentation.
Activate and enable the token inline hook
The token inline hook must be activated and enabled within your Okta Admin Console.
- Activating the token inline hook registers the hook with the Okta org and associates it with your external service.
- Enabling the token inline hook associates the hook with your Okta custom authorization server, which authenticates the Okta-Hosted Login sample application.
Note: Okta's Developer Edition makes most key developer features available by default for testing purposes. Okta's API Access Management product — a requirement to use Custom Authorization Servers — is an optional add-on in production environments.
Activate the token inline hook
Navigate to the Workflow > Inline Hooks page.
Click Add Inline Hook and select Token from the drop-down menu.
Add a name for the hook (in this example, "Patient Token Hook").
Add your external service URL, including the endpoint. For example, use your Glitch project name with the endpoint:
https://your-glitch-projectname.glitch.me/tokenHook
.Add the Authentication field and Authentication secret values. This example uses HTTP Basic Authentication.
- Authentication field =
authorization
- Authentication secret =
Basic YWRtaW46c3VwZXJzZWNyZXQ=
Note: If you want to use OAuth 2.0 to secure your inline hooks, see OAuth 2.0: Client Secret or OAuth 2.0: Private Key.
- Authentication field =
Click Save.
The token inline hook is now set up with a status of active.
Enable the token inline hook
Navigate to Security > API > Authorization Servers.
Select a custom authorization server from the list (usually default).
Select the Access Policies tab. Navigate to the Rule table and click the Edit icon next to the policy rule that will use the Inline hook. In most cases, edit the Default Policy Rule of the Default Policy.
From the Use this inline hook drop-down menu, select the token inline hook you activated ("Patient Token Hook").
Click Update Rule.
The token inline hook is now ready for triggering when the default policy rule is invoked from an authentication request.
Extend the sample Express application
The following code extends the local sample Node.js Express application to display the results of the token inline hook claim addition. This step is optional. The token inline hook is functional and the results of the implementation are shown in the external service logs, as well as in the system logs on your Okta org. But this extension is nice to have!
To extend the local sample Node.js Express application, you need to update the sample-web-server.js
file.
Update the web server page
- Navigate to your project folder
samples-nodejs-express-4
and continue to thecommon
folder (samples-nodejs-express-4/common
). - In an editor, open the
sample-web-server.js
page. - Locate the routing function
app.get('/profile'
and modify the function as in the code below. The Inline Token Hook code extension appears after theconst
declarations and before theres.render
function.
This extension renders the ID token, and if it contains the claim added by the token inline hook, adds this claim to the attributes array. This array displays claims on the user's My Profile page.
Preview and test the token inline hook
The token inline hook is ready for preview and testing. You now have the following applications configured:
- The Okta-Hosted-Login sample application (
samples-nodejs-express-4
) is ready to authenticate users from your Okta org. - The external service (Glitch.com project) is ready with code to receive and respond to an Okta token inline hook call.
- The Okta org is set up to call the external service when a token inline hook is triggered by a user sign-in from the Okta-Hosted-Login sample application, and ready to receive a response.
Note: Make sure you have users assigned to your application and at least one user is part of the Patients data store in your Glitch application.
Preview the token inline hook
In the Admin Console, go to Workflow > Inline Hooks.
Click the token inline hook name (in this example, "Patient Token Hook").
Click Preview.
From the Configure Inline Hook request block, complete the following fields:
- Select a user: A user in your org associated with your application
- Select an application: Your OIDC sample application name
- Select an authorization server: Your authorization server name. In this example, use
default
. - Select a grant type: Your application's grant type. In this example, use
Authorization Code
. - Select scopes: The granted scopes
Note: Based on your grant type selection, preview fields may vary.
From the Preview example Inline Hook request block, click Generate Request. You should see the user's request information in JSON format that is sent to the external service.
Note: You can also click Edit to modify this call for development or testing purposes.
From the View service's response block, click View Response. A response appears from your external service in JSON format, which either adds a claim to the token or doesn't based on your external service's logic.
Test your hook
Navigate to your sample application project folder (
samples-nodejs-express-4
).Start your Okta-Hosted-Login server (
npm run okta-hosted-login-server
).Navigate to your sample application (
http://localhost:8080
).Navigate to your Glitch.com project and open the Console Logs window (Tools > Logs).
Return to your sample application and sign in with an Okta user who is NOT in the Patients' data store.
- The user should sign in as normal; only the user name should appear in the Glitch log window.
- If you extended the sample application, click
My Profile
in the left-hand navigation pane. Only the user info claims are included in the table.
Sign out of the sample application, and now sign in with an Okta user who is in the Patients' data store.
- The user should sign in as normal; however, this user should have a patient ID displayed in the Glitch console output, as well as a successful implementation record of the token inline hook, available for review in your Okta org System Log (Reports > System Log).
- If you extended the sample application, click
My Profile
in the left-hand navigation pane. The patient ID is added as part of the Claims table.
Note: Review the Token inline hooks troubleshooting content or the Troubleshooting hook implementations section for information on any difficulties.
Next steps
Review the following guides to implement other inline or event hook examples:
See also
For further reference data on the token inline hook, see the token inline hook reference.