Introduction: the Okta Integration Network
Join Okta’s Network of 3,000+ App Integrations
Whether you are a CRM giant or the next hot HR startup, your customers want single sign-on (SSO) and automated provisioning to make end-user access and on-going management of your app simple and seamless. But, if you are like most rapidly growing SaaS providers, you want to avoid spending engineering cycles on implementing tedious identity requirements, and focus your team on your core features. Let Okta help!
Whether it’s cloud-based or on-premises, enterprise, consumer, or homegrown, the Okta Integration Network (OIN) allows Okta users seamless access to your application.
There are two distinct flavors of integration your app can support with Okta: Single Sign-On, allowing easy end-user access to your app, and Account Provisioning, providing IT-centralized control of apps, people, and groups.
Value to You and Your Customers
Single Sign-On Integration With Okta
Preparing Your App: Implementing Single Sign-on
The first step in making your application simple and manageable to use from an end-user and IT perspective is implementing a single sign-on protocol. Okta supports integration with a variety of single sign-on options including delegated authentication and proprietary vendor-specific protocols, but we recommend using a standards-based protocol such as Security Assertion Markup Language (SAML). SAML is the most widely used standard for implementing federated single sign-on. SAML eliminates the need for passwords by instead using digital signatures for authentication. Some additional benefits for SAML include:
Standards-based – SAML is based on a standard, ensuring interoperability across identity providers and offering enterprises the freedom to choose a vendor.
Usability – One-click access from portals or intranets, deep linking, password elimination, and automatic renewal of sessions make life easier for the user.
Security – Based on strong digital signatures for authentication and integrity, SAML is a secure SSO protocol, relied upon by the largest and most security-conscious enterprises in the world.
IT Friendly – SAML simplifies life for IT because it centralizes authentication, provides greater visibility, and makes directory integration easier.
How SAML SSO Works
The SAML specification defines three roles:
In the use case addressed by SAML, the user requests a service from the service provider. The SP requests and obtains an identity assertion from the identity provider. On the basis of this assertion, the SP makes an access control decision. In other words, it can determine whether it should perform a service for the connected user.
For more detailed information about SAML, check out the Oasis SAML Technical Overview, v2.0.
For some recommendations on how to implement mobile SSO, see the Box blog post on Rethinking Mobile SSO.
Okta's SAML toolkit for Java: The Okta SAML Toolkit for Java enables software developers to integrate SAML-based SSO authentication with Java web applications. All required documentation and code examples are included in a .zip file. Access the zip file from the Okta Download Page within the Okta app.
To access the .zip files from the Okta Downloads page, do the following:
The code examples in the toolkit include the source code for the on-premises components of our Jira and Confluence SAML integrations. These code examples include enhancements allowing you to validate users with Okta and for users to validate with the SP. Validation can be based on IP address, username, or defined JIRA and Confluence groups. Use these elements to modify or enhance the integrations. For more details, see Using the Confluence On Premises SAML App and Using the Jira On Premises SAML App.
Integrate with Okta: Supporting Single Sign-On in the OIN
Once an SSO protocol has been decided upon, Okta offers self-service tools (see Using the App Integration Wizard and Configuring the Okta Template SAML App) to enable SaaS companies to easily build and promote their single sign-on integrations to the Okta Application Network. We use SAML as a standard for single sign-on, but for apps that don't currently support SAML, you can simply use Okta's SWA option designed for apps that don't support federated sign-on methods.
Once you are ready to build and test an SSO integration with Okta, follow the steps below:
Resources: For details on using these tools, refer to the following video guides – App Wizard - SWA / App Wizard - SAML. Note: there are some instances where the App Wizard cannot be used (e.g., you want to pass “non-standard” attributes in the SAML assertion or to support “groups” via SAML). In such instances, you should use the Template App and submit to Okta for manual review. See App Wizard vs. Template App for details on the differences between each tool and the submission process.
The App Wizard works well for about 90% of the SSO use cases but it does not yet support some of the more complex ones (e.g., you want to pass “non-standard” attributes in the SAML assertion or to support “groups” via SAML). In these instances, please use the more full-featured template app described in Configuring the Okta Template SAML 2.0 App, and then submit the configured app details to Okta for manual review. To do so, email a screenshot of the configured template app with additional description to email@example.com.
When should you use the Template App?
Answer the following questions to determine whether a template app is the best choice:
Okta Verified vs. Community Created
There are two different "tiers" of app integrations in the OIN: Community Created and Okta Verified:
Okta Verified Requirements
Okta Verified Benefits
Account Provisioning Integration with Okta
Preparing Your App: Implementing Account Provisioning APIs
A provisioning API helps you deal with the “identity lifecycle”, or the different phases a user goes through, which includes onboarding, user profile changes, job changes and exit by connecting that company’s “source of truth” for identity, whether it is an HR system or a directory such as AD with your application. With Okta and its account provisioning capabilities, these changes can be recognized and used to trigger appropriate actions in the integrated applications. By exposing the necessary account provisioning APIs, your application can rely on an external system like Okta to manage and monitor users and access within your application. Here are some of the common “identity lifecycle” questions:
Most vendors provide administrative consoles to perform these tasks manually. For many customers, these operations are often tied to the overall identity lifecycle of each user. For example:
While not required, we recommend following the SCIM standard for designing a provisioning API, as it is meant to simplify the exchange of user and group identity information. For some good provisioning API implementations see the documentation for Box, GoogleApps, and Egnyte (SCIM). In general, we recommend a simple RESTful API with minimum support for the following:
1. Account Creation – A base user profile is created and user attributes are set. Attributes typically include a user login name, first name, last name, email, phone numbers, etc. It is a best practice to create an API that determines whether a user account already exists.
2. User Profile Management – Your app should always have the most up-to-date information for your users, as a profile will typically change during their time with an organization. Misaligned information, such as a change in email address, could make your app inoperable without an update. Your Account Provisioning API should allow a client to successfully set and retrieve profile information from the application.
3. Deactivation/Reactivation – When a user is terminated and should no longer have access to your application, their account should be disabled and de-activated. Such an event is typically triggered by an external identity lifecycle event. The employee may be changing his job role or leaving the company entirely, and no longer requires access to the app. From a compliance standpoint, account deactivation is a crucial capability. Your Account Provisioning API should support deactivation, but it should also allow for reactivation, as there are cases when re-activation is necessary.
4. Authorization Management – Whether your application uses group memberships or other types of authorization, memberships must be associated with users. Your customer may want to assign all the sales employees a particular set of app privileges—or have the membership of an Active Directory security group synchronized with a group within your app. Exposing APIs for group and authorization policy management allows authorization to be driven and managed by an external system.
General API Recommendations
Provisioning API Examples
Integrate with Okta: Supporting Account Provisioning in the OIN
Today, Okta engineering needs to build all Account Provisioning integrations and all requests must go through a thorough prioritization process. If you are interested in an Account Provisioning integration with Okta, please email firstname.lastname@example.org with the following details: a) links to your API provisioning documentation and b) background on your and your customer's needs (e.g., the names of specific joint customers asking for this functionality).
App Integration FAQs
Q: My application does not currently support SAML. Does Okta have resources to assist in my implementation of SAML?
Q: What is Secure Web Authentication (SWA)?
A: SWA was developed by Okta to provide SSO for apps that don't support federated sign-on methods. Users can still sign in directly through the application.
Q: I’m interested in a “Account Provisioning” integration with Okta. What do I do next?
A: Currently, Okta engineering builds all existing Account Provisioning integrations and all requests must go through a thorough prioritization process. If you are interested in an Account Provisioning integration with Okta, please email email@example.com with the following details:
Q: Are there any costs associated with joining the Okta Integration Network (OIN)?
A: No, integrating your application with the Okta Application Network is completely free. Okta’s paid SSO and Enterprise customers can also utilize application integrations in the OIN, free of charge.
Q: Great! My app is now in the OIN, what is the user experience for a joint customer that wants to set up SSO and Account Provisioning for my app in the Okta interface?
A: Okta creates unique SAML configuration documentation for every application in the OIN, so each one will be different. If you haven't already done so, sign up for a free, 30-day trial to test drive the Okta user experience.
Q: My app currently supports WS-FED for SSO. Can I use the App Wizard?
A: The Okta App Wizard only supports SAML 2.0 for federated SSO. If your app supports WS-Fed, you will need to create a WS-Fed Template App (see Configuring the Okta Template WS Federation Application) Once completed, the Template Application you create can only be used within your account. In order to promote your Template App to the OIN, please email a screenshot of the configured app details to firstname.lastname@example.org with your app name in the subject line.
Q: I’m setting up a SAML 2.0 app using the App Wizard and we have different domains for each customer. How do you manage these types of situations?
A: Currently, the App Wizard does not support custom domains. Therefore, Okta recommends creating your app as described in Configuring the Okta Template SAML 2.0 App. In order to promote your Template App to the Okta Application Network, please email a screenshot of the configured app details to email@example.com with your app name in the subject line.
Q: While creating a SWA app using the App Wizard, I realized that my app has additional fields that go beyond the standard username and password on the sign on page— Customer / OrgID, for example. Can an app with additional fields like this be configured using the App Wizard?
A: Currently, the App Wizard doesn't support extra sign-on fields. Okta recommends creating an app as described in Configuring Okta Template App and Plugin Template App. In order to promote your Template App to the Okta Application Network, please email a screenshot of the configured app details to firstname.lastname@example.org with your app name in the subject line.
Most web applications do not support SAML, and in most of these cases, Okta uses SWA. This sometimes requires the use of Okta’s browser extensions.
An 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.
An 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.
Tthe Okta Integration Network (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.
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:
Okta also provides free, open-source SAML Toolkits which partners and customers can use to build SSO for their apps.
Generally, a service provider (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.
Secure Web Authentication (SWA) is an 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.
An acronym for single sign-on. In an 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.
WS-Federation is an Identity Federations specification for single single-on, which is mostly used by Microsoft solutions, such as SharePoint and Office 365.