FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
      • Overview
      • Java Spring
      • Python Django
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Microsoft Azure AD B2C
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
        • Okta
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
        • Okta
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
      • URL Validation
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • PagerDuty
      • Tableau Cloud
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • Amazon API Gateway
      • Kong Gateway
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
    • Events & Webhooks
      • Overview
      • Writing a Webhook
      • Securing Webhooks
      • Events
        • Overview
        • Audit Log Create
        • Event Log Create
        • JWT Public Key Update
        • JWT Refresh
        • JWT Refresh Token Revoke
        • Kickstart Success
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • User Action
        • User Bulk Create
        • User Create
        • User Create Complete
        • User Deactivate
        • User Delete
        • User Delete Complete
        • User Email Update
        • User Email Verified
        • User IdP Link
        • User IdP Unlink
        • User Login Failed
        • User Login Id Dup. Create
        • User Login Id Dup. Update
        • User Login New Device
        • User Login Success
        • User Login Suspicious
        • User Password Breach
        • User Password Reset Send
        • User Password Reset Start
        • User Password Reset Success
        • User Password Update
        • User Reactivate
        • User Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Registration Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Application Specific Email Templates
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • Lambdas
      • Overview
      • Apple Reconcile
      • Client Cred. JWT Populate
      • Epic Games Reconcile
      • External JWT Reconcile
      • Facebook Reconcile
      • Google Reconcile
      • HYPR Reconcile
      • JWT Populate
      • LDAP Connector Reconcile
      • LinkedIn Reconcile
      • Nintendo Reconcile
      • OpenID Connect Reconcile
      • SAML v2 Populate
      • SAML v2 Reconcile
      • SCIM Group Req. Converter
      • SCIM Group Resp. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Self-Service Registration
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
      • Kickstart Custom Theme
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

    SAML v2 IdP Initiated With Okta

    FusionAuth Reactor logo

    This feature is only available in paid plans. Please visit our pricing page to learn more.

    Configure SAML v2 IdP Initiated SSO With Okta

    This page will guide you in configuring a SAMLv2 IdP Initiated Identity Provider with Okta as the initiating IdP. You will be able to visit an Okta provided link, authenticate, and then be logged into FusionAuth.

    This document assumes you have an admin account with Okta and a valid FusionAuth paid edition license.

    • Configure SAML v2 IdP Initiated SSO With Okta

    • Create and Partially Configure the Okta SSO Application

    • Add the Okta Public Certificate to FusionAuth

    • Add the SAMLv2 IdP Initiated Identity Provider

    • View the Identity Provider in FusionAuth

    • CORS Settings

    • Configure the FusionAuth Application Redirect URL

    • Complete SSO Configuration in Okta

    • Test It Out

    Create and Partially Configure the Okta SSO Application

    You will want to set up this application as an admin. Okta allows users with various permissions. Later, you will create a user that can log into the newly created application, Pied Piper.

    Navigate to the Okta admin screen. Using the left "hamburger" menu, click on Applications Header > Applications. From here, click Create App Integration. Select the SAML option and hit next.

    Setting up a SAMLv2 application in Okta

    Add an App name describing the application. Configure any other General Settings as needed (including adding your award winning logo).

    General settings tab when creating a SAMLv2 application in Okta

    Click "Next". You will arrive at the Configure SAML section.

    Settings tab when creating a SAMLv2 application in Okta

    Please complete the Single sign on URL and Audience URI (SP Entity ID) with placeholder data. We will return to these fields in a moment (with real data from FusionAuth). Click next to proceed.

    The final screen is related to marketing/support. This screen may or may not be present. Click the Finish button.

    Feedback Marketing Step

    Now, under the Sign On tab, scroll down until you see a button called "View SAML setup instructions". This will open a new window/tab. You will need the values displayed to complete the rest of this tutorial.

    View SAML Setup Instructions

    Record the Identity Provider Single Sign-On URL and Identity Provider Issuer values. The latter is a string such as http://www.okta.com/exkq14ymac31Bx7895d6.

    Download the "X.509 Certificate" too, then close the instructions tab.

    Details around certificate and SSO URL and issuer

    Add the Okta Public Certificate to FusionAuth

    Log in to the FusionAuth administrative user interface and navigate to Settings → Key Master.

    Import the Okta provided certificate you just downloaded.

    Adding the Okta certificate to Key Master

    Add the SAMLv2 IdP Initiated Identity Provider

    Navigate to Settings → Identity Providers. Add a SAMLv2 IdP Initiated Provider.

    • Configure the Name with a descriptive value.

    • Set the Issuer value to the Identity Provider Issuer value from Okta.

    • Set the Verification key to the public certificate you just imported.

    Enable this Identity Provider for any appropriate FusionAuth applications. For this example, Pied Piper allows the use of this Identity Provider.

    Any users who authenticate with Okta will be registered for this application because of the Create registrations setting.

    All other options may be left with default values. Save the configuration.

    Adding the IdP Initiated SSO Identity Provider

    View the Identity Provider in FusionAuth

    View the created Identity Provider and navigate to the SAML v2 Integration details section.

    Record the values of the Callback URL (ACS) and Issuer fields. Those will be used later.

    View the IdP Initiated SSO Identity Provider

    CORS Settings

    Navigate to Settings → System → CORS.

    Determine the hostname and scheme of the Okta Identity Provider Single Sign-On URL. If the URL is https://trial-6089629.okta.com/app/trial-6089629_test_1/exk1mn2r8kVgtAv6q697/sso/saml then the hostname and scheme are https://trial-6089629.okta.com.

    If you run into CORS configuration challenges, review the System > Event Log in the FusionAuth admin UI. This will tell you exactly what hostname and schemes must be added to the CORS allow lists.

    Add this value to the CORS Allowed origins field. Ensure that the POST method is checked in the Allowed methods field. Save the configuration.

    Additionally, you might have to add another entry with a trailing backslash, such as https://trial-6089629.okta.com/.

    Configure CORS

    Configure the FusionAuth Application Redirect URL

    Navigate to Applications → Your Application → OAuth. Update the Authorized redirect URLs field with one or more URLs. A redirect URL is where a user will end up after authentication and may be any valid URL.

    When a redirect URI is not specified, the first configured value will be utilized. To specify a specific redirect URL, follow the instructions below.

    Ensure the Authorization Code grant is enabled.

    Configure the FusionAuth Pied Piper application

    Complete SSO Configuration in Okta

    Return to the Configure SAML Tab. This can be found by navigating as follows from the App homepage: General > SAML Settings > Edit Button > General Settings > Next Button > Configure SAML tab in the Okta Admin screen.

    • Set the value of the Single sign on URL to the value of the Callback URL (ACS) from the FusionAuth Identity Provider recorded above.

    • Set the value of the Audience URI (SP Entity ID) to the value of the Issuer recorded above.

    • Optionally set the value of Default RelayState if you want to provide a specific redirect URI. If this value is omitted, the first Authorized redirect URI found in the FusionAuth Application OAuth configuration will be used. This option is supported in FusionAuth version greater than or equal to 1.41.0. In prior versions, append a query parameter redirect_uri= to the value specified in Single sign on URL to control the final redirect URI. Please note, the URL must be encoded. For more information see section below.

    • Set the Application username to be Email.

    Configure Okta with the FusionAuth SP information

    There are a few additional configuration changes you can make to enable certain functionality. This includes storing persistent Ids in FusionAuth, receiving emails from Okta, and configuring a custom redirect page for the end user. The next sections detail this optional set up. If not needed, please save the Okta application by clicking "Next" until complete and skip to Adding a User to the Okta Application .

    Optional: Adding a Specific Redirect After SAML login

    If you want a user to return to a specific redirect url after SAML authentication is complete, there are two options to specify this URL:

    1. Add to Relay State field

      • As of version 1.41.0 FusionAuth allows adding a redirect in the relay state.

      • Simply add something like https://hooli.com to the Default RelayState in your Okta configuration.

    2. Add to the ACS

      • You can append your redirect to the Single sign-on URL (ACS)

      • Example:
        https://example.com/acs/22cea679-83af-422a-806a-baae792b3ab9/85a03867-dccf-4882-adde-1a79aeec50df?redirect_uri=http%3A%2F%2Fhooli.com

    Showing Setting the Relay and ACS values

    The above values will need to be added to the Authorized redirect URLs OAuth configuration of your application in FusionAuth. Additional information can be found in our SAML. overview documentation.

    Optional: Setting a Persistent Id and Sending Email as an Attribute

    Ensure you are still on the Configure SAML Tab. This can be found by navigating as follows from the App homepage: General > SAML Settings > Edit Button > General Settings > Next Button > Configure SAML tab in the Okta Admin screen.

    At times it may be helpful to receive a unique and immutable id from Okta and tie this to the new FusionAuth user (this is the value of a persistent SAML NameID). To enable this, on the Edit SAML Integration Okta (current) screen please click Add Another under the Attribute Statements section. Under the Name field enter userId, for Name format leave as Unspecified, and finally, for Value enter user.id. With this attribute added, Okta will be sending over a persistent Id for each user.

    You can also instruct Okta to send over another attribute in the AuthN Response of email. Under the Name field enter email, for Name format leave as Unspecified, and finally for Value enter user.email.

    This is useful for when your linking strategy is based on email addresses.

    Add Persistent Id and email attribute statements

    By configuring Okta to send these two values you will be receiving an AuthN Response similar to the below:

    
    <saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" ... >
    // ...
        <saml2:AttributeStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
          <saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">erlich@fusionauth.io</saml2:AttributeValue>
          </saml2:Attribute>
          <saml2:Attribute Name="userId" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">11t9vmcte3QO77udv</saml2:AttributeValue>
          </saml2:Attribute>
        </saml2:AttributeStatement>
    // ...
    </saml2p:Response>

    You can tell FusionAuth how to find and use this persistent userId by modifying your newly created SAML IdP Initiated Provider in FusionAuth under the Options tab. Here you will add the value userId to the Unique Id claim field. Additionally, on the same tab, you can instruct FusionAuth where to find the email claim by filling in the Email claim with the value email. Depending on your Okta configuration, you can optionally indicate Use NameID for email instead.

    Configure FusionAuth with Email and Id attributes defined

    Adding a User to the Okta Application

    Navigate to the General tab and scroll to the App Embed Link section and note the Embed Link value. This is the link a user needs to visit to begin the IdP initiated SSO, so you could place it in your application’s navigation, launchpad, or elsewhere.

    Finally, click on the Assignments tab and assign the user to the application. First, select the user by clicking the Assign dropdown. Then by clicking Assign to People, and then finally selecting the Assign button for the user you would like to use.

    Pick a user to assign to application step one

    Then confirm the user should have access.

    Assigning a user to the SAML SP application step two

    Test It Out

    Open an incognito browser window and visit the Embed Link value. This value can be found at the bottom of the General tab of your Okta Application configuration, in the App Embed Link section. Log in with your Okta IdP credentials.

    Logging in with Okta

    When you authenticate successfully, you will eventually land at the URL configured in the application’s Authorized redirect URLs field. The full URL contains an authorization code.

    Since you configured registration for this Identity Provider, if the user did not previously exist in your FusionAuth instance, they will now have an account.

    For a production application, the next step would involve exchanging the authorization code by your application for a JWT from FusionAuth.

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.

    © 2023 FusionAuth
    How-to
    Subscribe for developer updates