This article is a brief overview of how to configure a SAML application.

• Custom SAML 2.0
• Authentication
• Secure Assertion Markup Language (SAML)
• Single Sign-On (SSO)

NOTE: Okta does not support the direct import of Service Provider(SP) application metadata. However, the relevant fields in the metadata can be used to configure a custom SAML app in Okta.
 

To create a custom SAML 2.0  application within Okta using the SP application's metadata, please follow the video or steps below.

1. Navigate to Okta Admin Dashboard > Applications > Applications.

2. Select Create App Integration > SAML 2.0.

3. On the General Settings tab, enter the App name value > Click Next.

4. Before configuring the SAML settings within the custom app, one must be ready to reference the Service Provider metadata file (usually a .xml file).
   For example, this is what a SAML .xml metadata file contains:

   <?xml version="1.0" encoding="UTF-8"?>
   <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
   entityID="http://mymachine.mycompany.com:8830">
      <md:SPSSODescriptor
   AuthnRequestsSigned="true"
   WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
         <md:KeyDescriptor use="signing">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
               <ds:X509Data>
                  <ds:X509Certificate>MIIC0TCCAbkCAQAwXDELMAkGA1UEBhMCSU4xCzAJBCgKCAQEAmEwfAFLjgDO
                      BgNVBAoTCXJicHJpdmF0ZTELMAkGA1UECxMCUUExETAPBgNVBAMTCHJhamt1bWFyMIIBIjANBgkq
                      hkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmEwfAFLjgDOEZk1AYPhX7dbYMXqkk4rF3uyYZeoMnnXP
                      Ls463GzGvVPnRgjTdIzm+1QOnkTx3BBu7kxlhtze2Sr7rtHLs1FYbzXREs5aVgIPnpkfuKdR9QND
                      aJJ1byxStnF+zI4feSYmHXsVWfHm24+FK0kCk3tSnw2/noXyW5xc2UbrGLYqaezpPSlf5WJ3isKF
                      lQr2k+HKXh4Rid4TUmEaoZXPAcB7QtkBYnIxzzmBoFCWSSsVldPRkaw=</ds:X509Certificate>
               </ds:X509Data>
            </ds:KeyInfo>
         </md:KeyDescriptor>
         <md:NameIDFormat>
   urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
         <md:
   AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
   Location="http://mymachine.mycompany.com:8830/router/login/loginSaml" index="0" isDefault="true" />
      </md:SPSSODescriptor>
   </md:EntityDescriptor>
   

5. Note the following values of these tags from the metadata file:

• AssertionConsumerService (ACS)
• NameIDFormat
• entityID
• relayState (optional)

6. Back to Configure SAML in the custom application, configure the Single Sign-On URL (ACS), Audience URI (SP Entity ID), Default RelayState (optional), and Name ID format from the values noted from the metadata.xml file from the Service Provider, and select Next.

   a. Single Sign-On URL: The Single Sign-On URL value is the value between the AssertionConsumerService tags. From the example metadata file, the value is http://mymachine.mycompany.com:8830/router/login/loginSaml
   1. If multiple values are found for the AssertionConsumerService Location, they can be configured by unchecking the Use this for Recipient URL and Destination URL checkbox.

2. Audience URI (SP Entity ID): The Audience URI (SP Entity ID) value is the entityID value in the metadata file. From the example metadata file, the value is http://mymachine.mycompany.com:8830.
3. Default RelayState: This is an optional value that can be skipped if unnecessary.
4. Name ID format: The default value for our example Name ID format is "Unspecified". From the example metadata file, the value is urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified. The example value corresponds to the Unspecified default value in Okta. The NameIDFormat tag in the metadata file may vary from SP to SP and contain a different name ID format; verify which one matches the metadata being configured in the Okta Organization. 

7. Select either I'm an Okta customer adding an internal app or This is an internal app that we have created, then select the Finish button.
8. Once the custom SAML application is configured within Okta, select the Sign-On tab and select the View SAML setup Instructions located on the right side of the webpage. These instructions will contain the Okta application Identity Provider Single Sign-On URL, the Okta application Identity Provider Issuer (EntityID), and the Okta application Identity Provider X.509 certificate. This information will be needed to provide to the SP admin to configure within their application.
9. Once the IdP metadata has been properly set on the SP app, assign the application to a test user in Okta and test the SAML login flow. Please check the Related References section for more information.

NOTE: These are very simple instructions on how to create a SAML application within Okta. It is possible that the Service provider may require additional information, such as custom attributes or additional settings, to get SSO to function.

Related References

• Troubleshoot any issues with SAML-tracer
• Beginner's Guide to SAML
• How to Configure a Custom SAML App
• How To Define and Configure a Custom SAML Attribute Statement