Create a SAML integration using AIW

SAMLAn acronym for Security Assertion Markup Language, SAML is an XML-based standard for exchanging authentication and authorization data between an identity provider (IdP) and a service provider (SP). The SAML standard addresses issues unique to the single sign-on (SSO) solution, and defines three roles: the end user, the IdP, and the SP. Here's how SAML works through Okta: SP-initiated flow: the end user requests (principally through a browser) a service from the SP. The SP requests and obtains an identity assertion from the IdP (in this case, Okta). On the basis of this assertion, the SP can decide whether or not to authorize or authenticate the service for the end user. IdP-initiated flow: with Okta as the IdP, an end user goes to the Okta browser and clicks on an app, sending a SAMLResponse to the configured SP. A session is established with the SP, and the end user is authenticated. integrations use Federated AuthenticationAuthentication is distinct from authorization, which is the process of giving individuals access to system objects based on their identity. Authentication merely ensures that the individual is who he or she claims to be, but says nothing about the access rights of the individual. Authentication methods and protocols include direct auth, delegated auth, SAML, SWA, WS-Fed, and OpenID Connect. standards to give end usersEnd users are people in your org without administrative control. They can authenticate into apps from the icons on their My Applications home page, but they are provisioned, deprovisioned, assigned, and managed by admins. one-click access to your SAML appAn abbreviation of application. Essentially, it is a web-based site used to perform any number of specific tasks, and requires authentication from end users by signing in.. The AIW generates the XML needed for the SAML request.

Before you begin

• Ensure that you add Okta to your browser's whitelist for 3rd-party cookies to prevent errors in your SAML integrations. See Whitelisting Okta for Third-Party Cookies for detailed instructions.

Task 1: Launch the Wizard

1. Verify that you are using the AdminAn abbreviation of administrator. This is the individual(s) who have access to the Okta Administrator Dashboard. They control the provisioning and deprovisioning of end users, the assigning of apps, the resetting of passwords, and the overall end user experience. Only administrators have the Administration button on the upper right side of the My Applications page. Console. If you are using the Developer Console, you need to switch over to the Admin Console. If you see < > Developer Console in the top left corner of your console, click it, then click Classic UI to switch.
2. In the Admin Console, go to Applications > Applications.
3. Click Add Application.
4. Click Create New App.
5. To create a SAML integration, select Web as the Platform and SAML 2.0 for the Sign on method.
6. Click Create.

Task 2: Configure general settings

• App name — Specify a name identifier for your integration.
  

  Note

  The name can only consist of UTF-8, 3 byte characters

• Optional. App logo — Add a logo to accompany your integration in the Okta orgThe Okta container that represents a real-world organization.. The logo must be a .png, .jpg, or .gif file and have dimensions of less than 1400 by 400 pixels. It also must be smaller than 100 kilobytes in size.
• App visibility — Choose whether to hide your integration from your end-users' homepage. Choose whether to hide your integration from the Okta Mobile Apps Store on your end-users devices.

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 completing each field, use your app-specific documentation and the Okta tool tips.

• Single sign on URL — The location where the SAML assertion is sent with a POST operation. This URL is required and serves as the default ACS URLACS Endpoint – Assertion Consumer Service URL – often referred to simply as the SP login URL. This is the endpoint provided by the SP where SAML responses are posted. The SP needs to provide this information to the IdP. value for the Service Provider (SPAn acronym for service provider. Generally, an SP is a company, usually providing organizations with communications, storage, processing, and a host of other services. Within Okta, it is any website that accepts SAML responses as a way of signing in users, and has the ability to redirect a user to an IdP (e.g., Okta) to begin the authentication process.). This URL is always used for IdPAn acronym for Identity Provider. It is a service that manages end user accounts analogous to user directories such as LDAP and Active Directory, and can send SAML responses to SPs to authenticate end users. Within this scenario, the IdP is Okta.-initiated sign-on requests.
  • Use this for Recipient URL and Destination URL — Select this check box if you want the recipient and destination URL to be the same.
    • Recipient URL — (Appears if the previous check box is not selected.) The location where the application may present the SAML assertion. This is usually the Single Sign-On (SSOAn acronym for single sign-on. In a SSO system, a user logs in once to the system and can access multiple systems without being prompted to sign in for each one. Okta is a cloud-based SSO platform that allows users to enter one name and password to access multiple applications. Users can access all of their web applications, both behind the firewall and in the cloud, with a single sign in. Okta provides a seamless experience across PCs, laptops, tablets, and smartphones.) URL.
    • Destination URL — (Appears if the previous check box is not selected.) The location where the SAML Response is intended to be sent inside the SAML assertion. This should be the same location as the Single sign on URL unless your application explicitly defines a specific value.
  • Allow this app to request other SSO URLs — For use in SP-initiated sign-in flows. Select this option to configure multiple ACS URLs to support applications capable of choosing where the SAML Response is sent. Specify an index or URL to uniquely identify each ACS URL endpoint. If an AuthnRequest message does not specify an index or URL, the SAML Response is sent to the default ACS URL specified in the Single sign on URL field.
    • Requestable SSO URLs — (Appears if the previous check box is selected.) Enter the SSO URLs for any other nodes.
• 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 you are sending in the SAML Response. Consult the SP documentation to determine which format to use, but use the default (Unspecified) if the application does not explicitly specify a format.
• Application username — The default value to use for the username with the application.
  


Important

To maintain security, do not use fields that can be edited by end users.

• Show Advanced Settings

  • Response — Choose Signed  or Unsigned to determine whether the SAML authentication response message is digitally signed by the IdP.
  • 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 or not 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 public key certificate used to encrypt the SAML assertion, and then click Upload Certificate  to upload the certificate.
    

    Note

    The certificate file must have a .cer file extension.

  • Enable Single LogoutA SAML Service Provider sends a logout request to the Identity Provider which results in both the Identity Provider and Service Provider’s current session to close. Okta only supports SP-initiated log out. — Allows users to sign out of both a configured custom app and Okta with a single click (but not out of other apps that may be open). For more information, see the section Single Logout Profile in the Profiles for the OASIS Security Mark Up Language (SAML) version 2.0 guide.
    • If Enable Single Logout is specified, the following three choices are available.
      • Single Logout URL  — Specify where you want to send the sign-out response.
      • SP Issuer  — The issuer for the service provider.
      • Signature Certificate  — Determines the public key certificate used to verify the digital signatures. Browse to the certificate, then click Upload Certificate. You need to upload the certificate in order to make the Single Logout functionality work properly.
      

      Note

      If SAML Single Logout is configured, a field for Identity Provider Single Logout URL appears in the SAML 2.0 setup instructions.

  • Authentication context class — Tells you the type of authentication restriction; usually set with the default PasswordProtectedTransport. Consult the SP documentation to obtain this information.
  • Optional. Honor Force AuthenticationUsers will be forced to re-authenticate through their Identity Provider when trying to access an app. Users will be required to re-authenticate even if they have an active session with the IdP already. For Okta, this means that it will also re-evaluate app sign-on policy if it was previously configured. — When set to Yes, your users are prompted for their credentials when a SAML request has the ForceAuthn attribute set to true, even if they are already signed in to Okta. Users will need to enter their credentials, even if they normally sign in through Desktop SSO. If this option is set to No, the attribute is ignored.
  • 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 OINAn acronym for the Okta Integration Network. The OIN is comprised of thousands of public, pre-integrated business and consumer applications. As an on-demand service, OIN integrations are continuously validated, always up to date, and constantly growing both in number and capability. Okta performs a single integration with an ISV or SP, providing thousands of end users with point-and-click customization for their orgs. integration that requires additional 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 new 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.
  Define Attribute Statements

  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 of the user and group attribute statements.
  • Name Format — the format in which the Name attribute is given to your application. The formats are:
    • Unspecified - can be any format defined by the Okta profile and must be interpreted by your application.
    • URI Reference - the name is provided as a Uniform Resource Identifier string.
    • Basic - a simple string; the default if no other format is specified.
  • 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 additional statement row.
  • Repeat until all necessary attributes are defined.

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

  Profile Editor

  • In the Admin Console, go to Directory > Profile Editor, and find the integration you just created. Click Profile.
  • In the Attributes screen that opens, click Add Attribute.
  • Add a new attribute and click Save
  • In the Admin Console, go to Applications > Application and click the app name.
  • In the screen that opens, click the General tab. Then click Edit in the SAML Settings section.
  • In the screen that opens, click Next.
  • In the Attribute Statements (Optional) section, type in the name of the attribute you just created in step 3. This value does not populate the drop-down box automatically. For the Value, type "appuser", a period, and the attribute name. For example, if your attribute is named NewRole, the Value is appuser.NewRole.
  • When done, click Next.
  • On the Applications page, click the integration name, then click the Assignments tab. Click Assign, and select Assign to GroupsGroups allow you to organize your end users and the apps they can access. Assigning apps to large sets of end users is made easier with 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.
  Define Group Attribute Statements

  In the Group Attribute Statements (Optional) section:

  • Enter the Name of the group attribute in your SAML app.
  • Select a Name Format.
  • Choose a Filtering option for your expression: Starts with, Equals, Contains, or Matches regex
  • Type in the expression that will be used to match against the Okta GroupName values and added to the SAML assertion.
  • Click Add Another to add an additional group statement row
  • Repeat until all necessary groups are defined.



Note

The Dynamic SAML feature does not 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 are an Okta customer adding an integration that is intended for internal use only:

• Select I'm an Okta customer adding an internal app
• Click the check box for This is an internal app that we have created or, if your app requires additional SAML configuration instructions to work with Okta, click the check box for 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 are an ISVAn acronym for independent software vendors. Okta partners with various ISVs (usually producing enterprise applications) to integrate on-premises, in the cloud, or native-to-mobile devices with Okta. that 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 are satisfied that all settings are correct and you have completed your preliminary testing, click Submit your app for review. This opens the OIN manager site and begins the OIN submission process.

Next steps

• If your integration does not behave as expected, contact Okta support at support@okta.com for assistance.
• Assign and unassign apps to users
• Assign apps to groups
• Submit an app integration to the OIN