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 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. Integration Wizard (AIW). The AIW allows you to create custom SWAAn acronym for Secure Web Authentication. SWA is a SSO system developed by Okta to provide single sign-on for apps that don't support proprietary federated sign-on methods or SAML. Users can enter their credentials for these apps on their homepage. These credentials are stored such that users can access their apps without entering their credentials each time. When users first sign-in to a SWA app from their homepage, they see a pop-up message asking if they were able to sign-in successfully., 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. 2.0, and OpenID Connect (OIDC) apps with immediate functionality. Once you create an app, you can assign it to usersIn Okta literature, we generally refer to "users" as the people who serve as Okta administrators. When we refer to "end users" we are generally referring to the people who the administrators serve. That is, those who use Okta chiclets to access their apps, but have no administrative control..
Launching the Wizard
- From the Administrator Dashboard, go to Applications.
- Click Add Application.
- First make sure that the app you want to add is not already in the OANAn acronym for the Okta Application Network. The OAN is comprised of thousands of public, pre-integrated business and consumer applications. As an on-demand service, OAN 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. by using the search and filtering tools. If you cannot find the app by searching, click Create New App.
- Select the type of app you want to create: SWA or SAML 2.0, or OpenID Connect.
- Click Create.
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 firstname.lastname@example.org for assistance.
- 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.
- Configure how users sign in:
- Who sets the credentials? – Choose who will set up the initial password and username credentials, end users or your orgAn abbreviation of organization, but can also be thought of as a company. A company that uses Okta as their SSO portal is generally referred to as an org. As an administrator, you decide how Okta should be displayed and/or integrated with your org. 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 (shown below) on the upper right side of the My Applications page..
- Application username Choose the format to use as the default username value when assigning the application to end usersIn Okta literature, we refer to "end users" as the people who have their own Okta home page (My Applications), using chiclets to authenticate into all of their apps. End users do not have any administrative control. When we refer to "users" we are generally referring to the individual(s) who have administrative control..
- Click Finish.
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
- 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.
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 a required and serves as the default ACS value for the Service Provider. 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.
- Allow apps to request other URLs –For use in 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.-initiated sign-in flows. Select this option to configure multiple ACS URLsACS 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 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.
- Use this for Recipient URL and Destination URL – Select this box if you want the recipient and destination URL to be the same.
- 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.
- 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, click Learn More.
- Group Attribute Statements (Optional) – If your org supports a large number of 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., use this option to filter them into a single SAML assertion. Filtering options include Starts With, Equals, Contains, and Regex expressions.
- 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.
- 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 Profiles for the OASIS Security Mark Up Language (SAML) version 2.0.
- 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.
- Request compression – Depends on the app and indicates whether or not the app will send the SAML Request compressed. Consult the SP documentation to obtain this information. Note: If you have the Early Access SAML 2.0 Auto-Compression feature enabled, this menu will not appear. Call Okta Support for enablement.
- 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 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..) If this option is set to No, the flag 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 OAN 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.
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 OAN. If you check this box, the following displays regarding Okta VerifiedEach app found in the Okta Applications page has either an Okta Verified, Community Created, or Community Verified designation. Okta Verified indicates that the app was created either from the OAN or by Okta community users, then tested and verified by Okta. 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.
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.
Before you begin
You need four pieces of information before you begin setting up an OIDC app in Okta.
- The platform for the app. Available platforms include webA web app is accessed through the browser and can remain running on a server that can store a secret safely., native onlyA native app resides on the end user's device., and single page appA 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).
- Any redirect URIs. A redirect URI is where Okta sends the authentication response and ID token. You can specify more than one.
- If your app is a web or a native app, decide whether or not to use refresh tokens.
- 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 clientEssentially, a client is anything that talks to the Okta service. Within the traditional client-server model, Okta is the server. The client might be an agent, an Okta mobile app, or a browser plugin. 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.
- Select Applications > Add Application > Create New App to start the wizard.
- Select the platform for the app, select OpenID Connect in the Sign on method section, and then click Create.
- In General Settings enter an app name and (optionally) upload a logo.
- Click Next.
- In Configure OpenID Connect, add a Redirect URI(s).
- Click Finish.
- Specify General Settings options:
Options on the General tab are similar for all app types:
- Web apps
- Choose from three 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 chicletsThe "buttons" that appear on an end user's Home page and represent each application they wish to access through Okta. Clicking the chiclet allows the end user to instantly sign in and authenticate themselves into their chosen app. 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.
To identify the search term for the groups claim, go to the Sign On tab and click Edit in the OpenID Connect ID Token dialog.
Note: 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.