Create SAML app integrations

SAML app integrations use federated authentication standards to give end users one-click access to your SAML application. The App Integration Wizard (AIW) generates the XML needed for the SAML request.

Before you begin

If your app integration contains links to instructions, prevent access issues by adding Okta to your list of sites that can always use cookies. See Allow third-party cookies.

Task 1: Launch the Wizard

  1. In the Admin Console, go to Applications > Applications.
  2. Click Create App Integration.
  3. Select SAML 2.0 as the Sign-on method.
  4. Click Next.

Task 2: Configure general settings

  • App name: Specify a name for your integration using UTF-8 3-byte characters.
  • App logo: Optional. Add a logo to accompany your integration in the Okta org. The logo file must be PNG, JPG, or GIF format and be smaller than 1 MB in size. For best results, use a PNG image with a transparent background and a landscape orientation. Use a minimum resolution of 420 x 120 pixels to prevent upscaling.
  • App visibility: Choose whether to hide your integration from your end users' homepage.

Task 3: Configure SAML settings

A SAML 2.0 configuration requires a combination of information from both your org and the target app. For help with completing each field, use your app-specific documentation and the Okta tool tips.

  • Single sign-on URL: The location to send the SAML assertion using a POST operation. This URL is required and serves as the default Assertion Consumer Services (ACS) URL value for the Service Provider (SP). This URL is always used for Identity Provider (IdP) initiated sign-on requests.
    • Use this for Recipient URL and Destination URL: Select this checkbox if you want the recipient and destination URL to be the same.
      • Recipient URL: (Appears if the previous checkbox isn't selected.) The location where the application can present the SAML assertion. This is usually the Single Sign-On (SSO) URL.
      • Destination URL: (Appears if the previous checkbox isn't selected.) The location to send the SAML Response, as defined in the SAML assertion. This should be the same location as the Single sign on URL unless your application explicitly defines a specific value.
  • Audience URI (SP Entity ID): The intended audience of the SAML assertion. This is usually the Entity ID of your application.
  • Default RelayState: The page where users land after a successful sign-in using SAML into the SP. This should be a valid URL. Consult the SP documentation to get this information.
  • Name ID format: The username format that you're sending in the SAML Response. Consult the SP documentation to determine which format to use, but use the default (Unspecified) if the application doesn't explicitly specify a format.
  • Application username: The default value to use for the username with the application.

    • To maintain security, don't use fields that end users can edit.

    • Response: Choose Signed or Unsigned to determine whether the IdP digitally signs the SAML authentication response message.
    • Assertion Signature: Choose Signed or Unsigned to determine whether the SAML assertion is digitally signed.
    • Signature Algorithm: Determines the signing algorithm used to digitally sign the SAML assertion and response.
    • Digest Algorithm: Determines the digest algorithm used to digitally sign the SAML assertion and response.
    • Assertion Encryption: Determines whether the SAML assertion is encrypted.

      The following three options appear when Encrypted is selected in the Assertion Encryption setting.

      • Encryption Algorithm: Select the encryption algorithm used to encrypt the SAML assertion.
      • Key Transport Algorithm: Select the key transport algorithm used to encrypt the SAML assertion.
      • Encryption Certificate: Browse to the public key certificate used to encrypt the SAML assertion, and then click Upload Certificate to upload the certificate.

        • The certificate file must have a .cer file extension.

    • Signature Certificate: Upload the public key certificate required to validate the SAML sign-in request and the Single Logout (SLO) request. Click Browse files... and click Open to upload the certificate from your local system. You must have a signature certificate to enable the checkbox for Enable Single Logout and Signed Requests.

    • Enable Single Logout: Allows users to sign out of both a configured custom app and Okta with a single click (but not out of other apps that are open). See the Single Logout Profile section in Profiles for the OASIS Security Mark Up Language (SAML) version 2.0.

      • If Enable Single Logout is specified, the following choices are available.

        • Single Logout URL: Specify where to send the sign-out response.

        • SP Issuer: The issuer ID for the service provider.

        If SLO is enabled, the SAML setup instructions for your app should include a field for the Identity Provider Single Logout URL.

    • Signed Requests: Validates all SAML requests using the Signature Certificate. The payload from the SAML request is validated, and Okta dynamically reads any single sign-on (SSO) URLs from the request.

    • Other Requestable SSO URLs: For use with SP-initiated sign-in flows. Enter the ACS URLs for any other requestable SSO nodes used by your app integration. This option enables applications to choose where to send the SAML Response. Specify a URL and an index that uniquely identifies each ACS URL endpoint.

      Some SAML AuthnRequest messages don't specify an index or URL. In these cases, the SAML Response is sent to the ACS specified in the Single sign on URL field.

      When you enable Signed Requests, Okta deletes any previously defined static SSO URLs and reads the SSO URLs from the signed SAML request instead. You can't have both static SSO URLs and dynamic SSO URLs.

    • Assertion Inline Hook: An Assertion Inline Hook is an outbound call from Okta to an external service that you created. This type of Inline Hook is triggered when Okta generates a SAML assertion in response to an authentication request. Before sending the SAML assertion to the app that consumes it, Okta calls out to your external service. The external service can respond with commands to add attributes to the assertion or modify its existing attributes.

      To have Okta call your external service, select the endpoint for the service from the dropdown list. If this option is left set to None (disabled), then no external service is called when an Assertion Inline Hook is triggered. See Inline Hooks, SAML Assertion Inline Hook Reference, and Enabling a SAML Assertion Inline Hook.

    • Authentication context class: Tells you the type of authentication restriction. The default is PasswordProtectedTransport. Consult the SP documentation to obtain this information.
    • Optional. Honor Force Authentication: Set to Yes to prompt users for their credentials when a SAML request has the ForceAuthn attribute set to true. Users are prompted to enter their credentials, even if they normally sign in through Desktop SSO. If this option is set to No, the attribute is ignored.

      This option only works with Integrated Windows Authentication (IWA)/agent-based SSO. It doesn't work with Agentless Desktop SSO (ADSSO).

    • Optional. SAML Issuer ID: Use this option when you need to override an Issuer ID. An override is required when more than one sign-in exists for a single application. It can also be used when you have an integration that requires extra attributes. Enter the Issuer ID to override the default value of http://www.okta.com/$(org.externalKey). Obtain the External Key from the setup instructions of the current working application instance.
  • Attribute Statements (optional): When you create a SAML integration, or modify an existing one, you can define custom attribute statements. These statements are inserted into the SAML assertions shared with your app.

    Each SAML assertion in the Attribute Statements (optional) section has these elements:

    • Name: The reference name of the attribute needed by your application. The maximum length for this field is 512 characters. The Name attribute must be unique across all user and group attribute statements.
    • Name Format: the format in which the Name attribute is given to your application. The formats are:
      • Unspecified: This can be any format defined by the Okta profile. Your application must be able to interpret this format.
      • URI Reference: The name is provided as a Uniform Resource Identifier string.
      • Basic: A simple string. This is the default format.
    • Value: The value for the attribute defined by the Name element. Admins can create custom expressions (using Okta Expression Language) to reference values in the Okta user profile. The maximum length for this field is 1024 characters.
    • Click Add Another to add an extra statement row.
    • Repeat until all necessary attributes are defined.

    After you add your attribute statements and create your SAML integration, you’ll need to update the profile using the Profile Editor.

    1. In the Admin Console, go to Directory > Profile Editor. Find the integration that you created and then click Profile.
    2. In the Attributes screen that opens, click Add Attribute.
    3. Add an attribute and click Save
    4. In the Admin Console, go to Applications > Applications. Click the app name.
    5. In the screen that opens, click the General tab. Then click Edit in the SAML Settings section.
    6. In the screen that opens, click Next.
    7. In the Attribute Statements (Optional) section, enter in the name of the attribute you created in step 3. This value doesn't populate the drop-down box automatically. For the Value, enter "appuser", a period, and the attribute name. For example, if your attribute is named NewRole, the Value is appuser.NewRole.
    8. When done, click Next.
    9. On the Applications page, click the integration name, then click the Assignments tab. Click Assign, and select Assign to Groups. In the window, click Assign to the right of the group. You can verify these assignments with a SAML tracer.
  • Group Attribute Statements (optional): If your Okta org uses groups to categorize users, you can add group attribute statements to the SAML assertion shared with your app.

    In the Group Attribute Statements (optional) section:

    1. Enter the Name of the group attribute in your SAML app.
    2. Select a Name Format.
    3. Choose a Filtering option for your expression: Starts with, Equals, Contains, or Matches regex
    4. Enter the expression to match against the Okta GroupName values and add to the SAML assertion.
    5. Click Add Another to add an extra group statement row
    6. Repeat until all necessary groups are defined.

    • The Dynamic SAML feature doesn't change the way attribute statements are entered or processed by the Okta Expression Language. This feature enables SAML attribute statements to be processed by apps in the Okta Integration Network. Previously the attribute statements were only available for apps created using the App Integration Wizard.

  • Click < > Preview the SAML Assertion to view the XML generated from the Configure SAML section of the SAML App Wizard.

Task 4: Configure feedback

If you're an Okta customer adding an integration that is intended for internal use only:

  • Select I'm an Okta customer adding an internal app
  • Select This is an internal app that we have created. However, if your app requires more SAML configuration instructions to work with Okta, select It's required to contact the vendor to enable SAML. Fill in the provided fields to help the Okta support team understand your SAML configuration.
  • Click Finish. Your integration is created in your Okta org.
  • The Settings page for your integration appears, where you can modify any of the parameters and assign your integration to users.

If you’re an independent software vendor who wants to add your integration to the Okta Integration Network (OIN):

  • Select I'm a software vendor. I'd like to integrate my app with Okta.
  • Click Finish. Your integration is created in your Okta org.
  • The Settings page for your integration appears, where you can modify any of the parameters and assign your integration to users.
  • After you’re satisfied that all settings are correct and you've completed your preliminary testing, click Submit your app for review. This opens the OIN manager site and begins the OIN submission process.

When you add an app integration from the OIN, Okta generates an Update application event that appears in the System Log. This event reflects the creation of a new instance of an existing app.

When you create an app using the App Integration Wizard (AIW), Okta generates a Create application event that appears in the System Log. This event reflects the creation of a new app.

Task 5: Manage Signing Certificates

After you create the SAML app integration, the SAML Signing Certificates section appears on the Sign On tab. You must configure your app integration to verify signed SAML assertions for SSO and trust Okta as the Identity Provider.

You might see two certificates available. If so, notice that one is active and one is inactive. The active certificate is scoped only for your app integration, while the inactive one is scoped for your entire org. Okta recommends keeping the app-only certificate active. Optionally, you can generate and activate a new certificate.

Perform the following steps to obtain the necessary settings to provide for your SAML app:

  1. Set the Status for the certificate that you want to be Active.

    If it isn’t active, select Activate in the Actions menu for another certificate, or click Generate new certificate and activate the new certificate.

    2. Your SSO configuration isn't complete until you perform the following steps.

  2. Under SAML Setup, click View SAML setup instructions.

  3. Depending on your application, either:

    • Copy the IdP settings and download the certificate
    • Copy all the IdP metadata if your application can consume it

Next steps

If your integration doesn't behave as expected, contact Okta Support.