Configuring a custom Security Assertion Markup Language (SAML) application adds specific applications that are not part of the Okta Integrated Network (OIN). The solution requires using the App Integration Wizard (AIW) to generate the XML needed for the SAML request by combining information from the Okta tenant and the target application. These integrations use federated authentication standards to grant end users one-click access to the SAML application.
- Okta Identity Engine (OIE)
- Okta Classic Engine
- Custom Application
- SAML 2.0
- Single Sign-On (SSO)
How is a Custom SAML Application Configured in Okta?
This video will show how to configure a custom SAML app.
NOTE: There is no official Okta documentation for configuring a custom SAML application. The application vendor must provide or confirm all details and settings available in the custom SAML application settings. This is a very important difference, since OIN apps usually include a SAML documentation page under the Sign-On tab.
Step 1: Create the App Integration
The following steps describe how to create a custom SAML 2.0 application integration in the Admin Console.
-
In the Admin Console, go to Applications > Applications.
-
Select Create App Integration.
-
Choose SAML 2.0 as the Sign-on method.
-
Select Next.
-
Enter a name in the App name field.
-
(Optional) Add a logo in the App logo field.
-
Select the App visibility setting.
- Select Next.
Step 2: Configure Core SAML Settings
The following steps describe how to enter the core SAML settings provided by the application vendor. The two most critical fields are defined below.
Core SAML Field Definitions:
-
Single Sign-On URL (ACS URL): The Assertion Consumer Service (ACS) URL is the endpoint on the service provider where Okta sends the SAML assertion after authentication. This value is provided by the application vendor.
-
Audience URI (Entity ID): The Entity ID is a globally unique identifier for the service provider. It tells Okta which application the SAML assertion is intended for. This value is also provided by the application vendor.
Complete the following steps to configure the SAML settings:
-
Enter the ACS URL in the Single sign-on URL field.
-
Enter the Entity ID in the Audience URI (SP Entity ID) field.
-
Set the Name ID format and Application username as directed by the vendor.
-
Configure any additional SAML attribute statements using the app-specific documentation and the Okta tooltips.
-
Select Next.
-
Complete the feedback section and select Finish.
NOTE: All custom SAML applications can be configured with a name and a logo. To identify a custom SAML application, navigate to the application's General tab. If the SAML Settings section is visible, the application is not an OIN application.
Step 3: Assign Users to the Application
The following steps describe how to assign users to the newly created SAML application so they can access it.
-
In the Admin Console, go to Directory > People.
-
Select the user to assign.
-
Navigate to the Applications tab.
-
Select Assign Applications.
-
Select the application created in the previous steps and select Save.
Alternatively, assign a group directly from the application:
-
Navigate to the application in Applications > Applications.
-
Select the Assignments tab.
-
Select Assign and choose Assign to Groups.
- Select the appropriate group and select Done.
Step 4: Retrieve the IdP Metadata
The following steps describe how to retrieve the Okta IdP metadata and provide it to the application vendor to complete the SAML trust on the service provider side.
-
Navigate to the application in Applications > Applications.
-
Select the Sign On tab.
-
Scroll to the SAML Signing Certificates section.
-
Select Actions next to the active certificate and choose View IdP Metadata to open the XML metadata in a browser, or download the metadata file directly.
-
Provide the metadata URL or downloaded file to the application vendor to complete the SAML configuration on their end.
NOTE: The IdP metadata contains the Okta Single Sign-On URL, the Issuer URI, and the signing certificate. The application vendor requires these values to establish the SAML trust relationship.
For additional troubleshooting, open a support case.
