Using the App Integration Wizard Skip to main content
https://support.okta.com/help/oktaarticledetailpage?childcateg=&id=ka02a0000005u9zsaq&source=documentation&refurl=http%3a%2f%2fsupport.okta.com%2fhelp%2fdocumentation%2fknowledge_article%2fusing-the-app-integration-wizard-1111708899
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
1
2
3
4
5
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Average Rating:
Using the App Integration Wizard
Published: Sep 14, 2017   -   Updated: May 15, 2018

okta-doc-source

Using the App Integration Wizard

If the application that you want to add does not already exist in the Okta Applications Network, create it with the App Integration Wizard (AIW). The AIW allows you to create custom SWA, SAML 2.0, and OpenID Connect (OIDC) apps with immediate functionality. Once you create an app, you can assign it to users.

Launching the Wizard

  1. From the Administrator Dashboard, go to Applications.
  2. Click Add Application.
  3. First make sure that the app you want to add is not already in the OIN by using the search and filtering tools. If you cannot find the app by searching, click Create New App.
  4. Select the type of app you want to create: SWA or SAML 2.0, or OpenID Connect.
  5. Click Create.
The SWA App Wizard

A SWA integration provides single sign-on for apps that don't support proprietary federated sign-on methods; it works with any web-based app. If you choose to use a SWA integration, step through the AIW to create the app.

If your SWA app integration is successful, the following happens when end-users click the app chiclet:

  • The username and password fields are populated.
  • Users are signed in to the app automatically.

If either of these conditions are not satisfied, or if the app does not behave as expected, contact Okta support at support@okta.com for assistance.

  1. Configure General Settings:
    • App name Provide a name identifier for the app.
    • App login page URL Copy/paste the full URL of the login page for the app. This URL may be different from the landing page.
    • Advanced Settings/Redirect URL Click the Advanced Settings link to expose the Redirect URL field. This additional field allows you to specify a redirect URL for the app.
    • App logo Review the tool tips for specifics on the type of image you can use for your logo.
    • App visibility – Choose whether to hide the application from your users' homepage or mobile app.
    • App type Check the This is an internal application that we created checkbox if (1) your company created the app (not just the integration) and(2) this app will never be publicly released.
  2. Configure how users sign in:
    • Who sets the credentials? Choose who will set up the initial password and username credentials, end users or your org admin.
    • Application username Choose the format to use as the default username value when assigning the application to end users.
  3. Click Finish.
The SAML App Wizard

A SAML integration provides Federated Authentication standards that allow end users one-click access to the app. The following fields generate the XML needed for the app's SAML request. If you choose to use a SAML 2.0 integration, step through the AIW to create the app.

Note: To prevent errors in your SAML integrations, ensure that Okta is whitelisted for 3rd-party cookies in your browser! See here for detailed instructions.

Note the following about SAML integration:

  • The app must support SAML.
  • The app that you want to integrate should have documentation that provides SAML specific information. Consult that documentation to complete the fields in section 2 of the AIW, Configure SAML.
  • If your SAML integration fails to perform, call your professional services representative for support.

The SAML app wizard has three main sections:

① General Settings

② Configure SAML

③ Feedback

① General Settings

  • App name Specify a name identifier for the app.
  • App logo Review the tool tips for details about the type of image you can use for your logo.
  • App visibility Choose whether to hide the application from your users' homepage or mobile app.

② Configure SAML

A SAML 2.0 configuration requires a combination of information from 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 an HTTP POST. This URL is required and serves as the default ACS value for the Service Provider. This URL is always used for IdP-initiated sign-on.
  • Use this for Recipient URL and Destination URL – Select this box if you want the recipient and destination URL to be the same.
  • Allow apps to request other URLs –For use in SP-initiated sign-in flows. Select this option to configure multiple ACS URLs to support apps 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 – (Displays if the checkbox above is selected) Enter SSO URLS for any other nodes.
  • Recipient URL – (Displays if the checkbox above is not selected) The location where the application may present the SAML assertion. This is usually the Single Sign-On URL.
  • Destination URL – (Displays if the checkbox above 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.
  • Audience URI – The intended audience of the SAML assertion. This is usually the Entity ID of your application.
  • Default RelayState – The page users land after successful login (via 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 SAMLResponse. 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 for a user's application username.
    Note: To maintain security, do not use fields that can be edited by end users.
  • Attribute Statements (Optional) – You can federate Okta user profile field values to SAML attributes. The Service Provider will use the federated SAML attribute values accordingly. For details on creating custom expressions, see Okta Expression Language.
  • Group Attribute Statements (Optional) – If your org supports a large number of groups, use this option to filter them into a single SAML assertion. Filtering options include Starts With, Equals, Contains, and Regex expressions.
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.

    Note: 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 upload the public key certificate to encrypt the SAML assertion, and then click Upload Certificate to upload the certificate.
    • Note: The certificate file must have a .cer extension in order to be uploaded.

  • Enable Single Logout – Allows users to log 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 guide .

    Note: The certificate file must have a .cer extension in order to be uploaded.

  • If Enable Single Logout is specified, the following three options are available.
    • Single Logout URL – Specify where you want to send the logout response.
    • SP Issuer – The issuer for the service provider.
    • Signature Certificate – Determines the public key certificate used to verify the digital signatures. Browse to select the certificate, then click Upload Certificate.

    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 at the default (PasswordProtectedTransport). Consult the SP documentation to obtain this information.
  • Honor Force Authentication (optional) – 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 logged in to Okta (users will need to enter their credentials even if they normally login through Desktop SSO.) If this option is set to No, the attribute is ignored.
  • SAML Issuer ID (optional) – Use this option when you need to override an Issuer ID. Such an override is required when more than one login exists for a single app. It can also be used when you have an OIN app that requires additional attributes. Enter the Issuer to override the default value of http://www.okta.com/$(org.externalKey). Obtain the External Key from the setup instructions of the current and working app instance.

Click the Preview the SAML Assertion button to view the generated XML derived from the Configure SAML section of the SAML app wizard.

③ Feedback

The feedback you provide helps Okta Support understand how you configured this application.

Are you a customer or partner? – Different options display depending on your selection.

Customer – For customers who are adding an external app:

  • App type – Select the checkbox if (1) your company created the app (not just the integration) and(2) this app will never be publicly released. If you check this box, you are not asked for further support information.
  • Contact app vendor – Select this box if contacting the vendor is mandatory for enabling SAML for the app. If you select this box, you are asked to provide further general information about your app to our support team.

Software vendor – For software vendors who are integrating their app with Okta:

  • Is your app integration complete? Select this box if your integration is ready for public use in the OIN. If you check this box, the following displays regarding Okta Verified status:
  • General information about what Okta Verified status is, and how to obtain it.
  • Fields for you to complete if you want to obtain Okta Verified status, such as a description of your app, and technical contact information.
The OpenID Connect Wizard

OpenID Connect is an identity layer on top of the OAuth 2.0 protocol. It verifies end-user identity and obtains profile information. For detailed information about OpenID Connect, see Welcome to OpenID Connect.

 

This is an Early Access feature. To enable it, please contact Okta Support.

User Consent for OAuth 2.0 and OpenID Connect Flows

A consent represents a user’s explicit permission to allow an application to access resources protected by scopes. As part of an OAuth 2.0 or OpenID Connect authentication flow, you can prompt the user with a popup or window to approve your app's access to specified resources. You can set up user consent as part of creating the app. Consent grants are different from tokens because a consent can outlast a token, and there can be multiple tokens with varying sets of scopes derived from a single consent. When an application comes back and needs to get a new access token, it may not need to prompt the user for consent if they have already consented to the specified scopes. Consent grants remain valid until the user manually revokes them, or until the user, application, authorization server or scope is deactivated or deleted, User consent requires that you org has the API Access Management feature enabled.

Before you begin

You need four pieces of information before you begin setting up an OIDC app in Okta.

  1. The platform for the app. Available platforms include web A web app is accessed through the browser and can remain running on a server that can store a secret safely., native only A native app resides on the end user's device., and single page app A SPA app is a web app that is contained on a single web page. All code is retrieved when the page is loaded initially; the page does not load or refresh. A SPA app cannot keep running on a server. (SPA).
  2. Any redirect URIs. A redirect URI is where Okta sends the authentication response and ID token. You can specify more than one.
  3. If your app is a web or a native app, decide whether or not to use refresh tokens.
  4. If your app is a SPA app, decide what kind of app visibility and login flow you want. You can configure your app to be initiated only in the background without an Okta chiclet, or configure login to be initiated either by the app or by Okta. If either the app or Okta can initiate the login, there are two flow options.
    • Redirecting to the app to start the login conforms to Section 4 of the OpenID Connect specification. When the end-users click an Okta chiclet, they are redirected to the initiate_login_uri of the client application, which constructs an authorization request and redirects the end-user back to Okta.
    • Sending an ID Token directly to the app is a simpler flow. Okta mints an ID Token and posts it directly to the first redirect URI registered for the client application. This is consistent with sign in for SAML apps. You can configure which OpenID Connect scopes are granted. The form_post response mode used for this flow. There is no state parameter included in the request, since it is a one-way request and not round-trip.

Procedure

  1. Select Applications> Add Application > Create New App to start the wizard.
  2. Select the platform for the app, select OpenID Connect in the Sign on method section, and then click Create.
  3. In GeneralSettings enter an app name and (optionally) upload a logo.
  4. Click Next.
  5. In Configure OpenID Connect, add Login or Logout Redirect URI(s).
  6. Click Finish.
  7. Specify General Settings options:

    Options on the General tab are similar for all app types.

    Note that redirecting to the app to start the login conforms to Section 4 of the OpenID Connect specification. When the end-users click an Okta chiclet, they are redirected to the initiate_login_uri of the client application, which constructs an authorization request and redirects the end-user back to Okta.

    • Web apps
      • Choose from four different grant type options.
      • Enter one or more redirect URIs where Okta will send OAuth responses.
      • Requires a client ID and a client secret.
    • Native apps
      • Choose from four different grant type options.
      • Enter one or more redirect URIs where Okta will send OAuth responses.

      • Requires a client ID
      • Select a Client authentication type:
        • Use PKCE (for public clients) — Recommended for native apps. By requiring a Proof Key for Code Exchange, this option ensures that only the client that requested the access token can redeem it.
        • Use Client Authentication — This option is not recommended for distributed native apps. A client secret is embedded in the client and sent with requests, proving the client's identity.
    • SPA apps
      • Single grant type option.
      • Enter one or more redirect URIs where Okta will send OAuth responses.
      • Requires a client ID.
      • Select a Login Initiated By setting:

        The Login Initiated By setting specifies whether the app is initiated only in the background or whether either the app or Okta can initiate the login. If you select App Only, the app is started in the background without an Okta chiclet. If you select Either Okta or App, you can utilize an Okta chiclet:

        • ​Select the appropriate Application visibility option.
        • Select the appropriate Login flow option. If you choose Send ID Token directly to app (Okta Simplified), you're also able to choose scopes.

        Note: You can use the API endpoint openid-connections to configure Okta interactions programmatically. When a Web app contains the value implicit for grant_types_supported, admins can publish chiclets with the Login Initiated By feature. For more information about OIDC clients and the API, see OpenID Connect.

        If you select Either Okta or App in Login Initiated By, you can also specify an App Embed Link.

    • Consent

      If User Consent is enabled the following section appears. If you want prompt the user with a popup or window to approve the app's access to specified resources, check the Require consent box. Additionally, set up the consent for a scope in your custom authorization, as described in the Create Scopes section of API Access Management.

      user-consent

  8. Click Save.

Set the Groups Claim Filter

To identify the groups claim filter, go to the Sign On tab and view the OpenID Connect ID Token section.

If the value you specify in Groups claim matches more than 100 groups, an error occurs when the API tries to create ID tokens. This limit is likely to change in the future. Most apps won't change the setting in Token Credentials, which displays along with the OpenID Connect ID Token dialog.

Post a Comment