Getting Started Guide: Okta Integration Network Skip to main content
https://support.okta.com/help/oktaarticledetailpage?childcateg=&id=ka0f0000000ay5pkaw&source=documentation&refurl=http%3a%2f%2fsupport.okta.com%2fhelp%2fdocumentation%2fknowledge_article%2fgetting-started-guide-okta-integration-network
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:
Getting Started Guide: Okta Integration Network
Published: Jan 12, 2015   -   Updated: Mar 30, 2018

Introduction: the Okta Integration Network
Single Sign-On Integration with Okta
Account Provisioning Integration with Okta
App Integration FAQs
Okta Terminology


top

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

  • Eliminate passwords and increase end-user adoption: Increase overall usability and simplify user access with federated SSO.
  • Integrate seamlessly with corporate directories: Integrate into Active Directory (AD) without disrupting your core product functionality. Customers can connect to AD in minutes—without firewall changes.
  • Automate user provisioning and synch: Okta integration enables IT admins to use directory group membership to automatically provision and de-provision user accounts in your app.
  • Reduce sales cycle friction: Avoid the conflicts with IT that center around service deployments, provisioning, and security. Firewall-restricted environments are no longer an issue.

top

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:

  • User the end-user trying to authenticate to the service.
  • Service provider (SP) the application or website the user is trying to sign into. Typical examples would be Box or GoogleApps.
  • Identity provider (IdP) the entity that actually authenticates the user (in this case, Okta).

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.

SP_ID.png

For more detailed information about SAML, check out the Oasis SAML Technical Overview, v2.0.

Mobile SSO

For some recommendations on how to implement mobile SSO, see the Box blog post on Rethinking Mobile SSO.

SAML Toolkits

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.

Note: You must have an active Okta account to access the Okta Java Toolkit. Don’t have an active account? Get started with a free, 30-day trial.

To access the .zip files from the Okta Downloads page, do the following:

  1. Log in as an Administrator.
  2. From the Dashboard page, click the Settings tab.
  3. On the Settings page, click Downloads.
  4. Scroll down to Admin Downloads and find Okta SAML Toolkit for Java.
  5. Click the Download button to start the download and follow the prompts.

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:

  1. Create an Account in Okta – The first step is to create an account in OktaNote: this is only a 30-day trial but we can extend the account as needed. Please email developers@okta.com to request an extension.
  1. Test Your SSO Implementation – If you simply want to test your application's SSO implementation with Okta, we recommend using a Template App. Template Apps can only be used within your Okta account. Resources: See the Configuring the Okta Template SAML 2.0 App and Configuring Okta Template App and Plugin Template App for instructions on using the templates.
  1. Build and Submit Your App – In order for your SSO integration to be added to the public Okta Application Network for all Okta customers to use, Okta must review and publish your app. The easiest way to submit an app to Okta for review is to use the App Integration Wizard. By using the App Integration Wizard, your SSO configuration details are automatically be routed to Okta for review and promotion upon submission. To access the App Integration Wizard, log into your Okta account and create a new app. To do so,
    1. From the Admin page, click the Applications tab.
    2. On the Application page, click the Add Application button.
    3. From the Add Application page, click the Create New App button.

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.

  1. Okta Review and Promotion – Okta reviews all apps submitted through the above App Wizard process, contacts ISVs as needed, tests the apps, and promotes them to the Okta Application Network. Note: Apps without test logins and internal URLs may be discarded. If you think your app has been discarded in error, please email developers@okta.com.

App Wizard vs. Template Apps

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 developers@okta.com.

When should you use the Template App? 

Answer the following questions to determine whether a template app is the best choice:

SAML 2.0

  • Do you want to pass non-standard attributes in the SAML assertion such as “Role”? Standard attributes are: User_FirstName, User_LastName, User_Email, User_Login
  • Do you want to pass “groups” in the SAML assertion from Active Directory or Okta?
  • Do you have unique subdomains per customer? For example, do your customers log in to a URL such as: http://acme.okta.com/saml/sso.okta.com?
  • Create an app using the Configuring the Okta Template SAML 2.0 App template.

SWA

WS-Fed

Okta Verified vs. Community Created

There are two different "tiers" of app integrations in the OIN: Community Created and Okta Verified:

  • Community Created – the app was created by the Okta community (partners and customers), but has not been officially tested and verified by Okta.
  • Okta Verified – indicates that the app was created either by Okta or by the Okta community. It has been tested, documented, and verified by Okta. The Okta verified status has several requirements and benefits.

Okta Verified Requirements

  • Two non-expiring developer / sandbox accounts in your product for Okta's use
  • Escalation points of contact to support the integration
  • Support contact (customer helpdesk)
  • Technical contact (product/engineering)
  • Business contact (business development/partnerships)

Okta Verified Benefits

  • App integration validated and continually tested by Okta
  • Direct points of contact at Okta for partnership and integration support
  • Free technical training via Okta University
  • Access to Okta Verified Partner content on the Okta Community
  • Okta logos branding you as an Okta Verified Partner
  • Invitations to Okta marketing, training, and networking events
  • Okta partner / developer notifications 

top

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: 

  • How is a user account created in your application?
  • How is a user profile updated?
  • How do you limit or grant user access to your application?
  • How are users synchronized with the customer identity source?
  • How do you align customer access policies across various applications?
  • How do you deactivate an account?

 

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:

  • An HR system creates the initial footprint of an employee, which should then trigger a new domain user to be created in Active Directory.
  • A VOIP telephone account should be created automatically for all new employees.
  • Everyone in the sales division should have an account in the corporate CRM application with basic privileges assigned.
  • When an employee leaves the company, their access to the various applications should be revoked.

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 BoxGoogleApps, 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.

 

API Functionality

Description (the ability to...)

Create User

…create a new user using a basic set of user attributes: first name, last name, email, etc.

Update User

…subsequently update user profiles. External changes on the user may require updates such as email address or a status update (e.g., disabling a user).

Get All Users

…get a list of all the users accounts in your app. A client may wish to easily obtain a full list of accounts. They may need to import users and their user profile details. You should consider both use cases.

Set User Status

…update user status is crucial. Again, the ability to activate and disable should be supported. If there are other app-specific statuses that should be exposed, make sure you include a way for the client to fetch the list of values, as they vary from app to app.

Get Permissions

…set any permission related attributes or relationships for a user. Depending on your app, these could be attributes within the user profile. There might be groups, roles or profiles (or a combination of these) that should be associated or granted to a user. The idea is to allow the API client to obtain a good picture of individual user access to your app.

Update Password

…reset user passwords. This allows a client who may be centrally managing end-user passwords to synchronize passwords into your app. If your app has a configurable password policy, it should be retrievable through some API. This allows your client to validate passwords accordingly when needed. Where possible, allow hashed values, as your client may not have access to the clear text value. Supply documentation to dictate the type of supported hash.

General API Recommendations

  • Use query-based API for searching where possible. Allowing flexible search criteria is key, as the parameters available to the client may not map to the unique identifier(s) in your API. Also, allow the client to specify what is returned. For example, an API used to fetch a user attribute (like first name, or manager’s name) should not return all the available attributes, leaving it up to the client to parse through the data. Such oversights can prove tedious and inefficient.
  • Proper error handling is important. A returned error should provide sufficient details for the client to figure out the problem. One good practice is to include a short, but precise, text explanation as part of the error. If error codes are being used, make sure the meaning of each code is clearly documented.
  • One key feature often missing is API-level logging on the app side. This is extremely useful when it comes to debugging issues during integration development. Without this, developers can only rely on returned errors, when available. Or they must depend on changes in the app itself to confirm success. An API log that clearly shows which API is being used, along with the passed parameters, can efficiently help to diagnose problems.
  • Think through each use case from the point of view of the API client. In many instances, API supported operations can easily be done through the product GUI involving one or more end users. Sometimes an operation may require multiple screens to capture the input. Certain sequential operations may require time delays in between or pending on another action to be executed. For example, workflows may be required due to end user approvals. Think of how an API client should cope with these complex scenarios. As part of the design, you may need to explore the option of a different workflow or business flow in the product to support your clients where it makes sense.
  • Good documentation is essential. This is the main channel of communication between you and the client developer and should include code documentation, code samples, setup information, and error details.

Provisioning API Examples

For some good provisioning API implementations see the documentation for Box and GoogleApps.

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 developers@okta.com 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).

top

App Integration FAQs


Q: My application does not currently support SAML. Does Okta have resources to assist in my implementation of SAML?

A: Yes, Okta offers SAML Toolkits and support to help you get started.

 

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.

User Experience: Users can then enter their credentials for these apps on The New Okta Home Page. These credentials are stored such that users can access their apps via SSO. When users first sign-in to a SWA app from their homepage, they will see a pop-up message asking if they were able to sign-in successfully.

 

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 developers@okta.com with the following details: 

  • Links to your API provisioning documentation.
  • Background on your needs and your customer's (e.g., names of specific joint customers asking for this functionality).

 

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 ApplicationOnce 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 developers@okta.com 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 developers@okta.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 developers@okta.com with your app name in the subject line.

top

Okta Terminology


Form-based Authentication

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.

IdP

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.

ISV

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.

OIN

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.

SAML

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 a chiclet, sending a SAMLResponse to the configured SP. A session is established with the SP, and the end user is authenticated.

Okta also provides free, open-source SAML Toolkits which partners and customers can use to build SSO for their apps.

SP

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.

SWA

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.

SSO

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

WS-Federation is an Identity Federations specification for single single-on, which is mostly used by Microsoft solutions, such as SharePoint and Office 365.

Post a Comment