Create a SAML authentication application

This article walks you through the process of creating a SAML authentication application that uses Okta as its identity provider. After completing this walkthrough, you’ll have an authentication client that can be used to create a custom providers that enables users to log on to your website by using their Okta SAML account.

📘

You’ll need an Okta developers account in order to complete this walkthrough. If you don’t have an Okta developers account, you can get a free one from https://developer.okta.com/login. Although the free account has limited capabilities, it will let you carry out all the tasks detailed in this walkthrough.

We should clarify upfront that the purpose of this article is to give you an idea of what’s involved in creating an authentication client; among other things, that means that this isn’t necessarily the best, the fastest, or the most effective way to create an Okta application. Instead, the intent is to show you some of the tasks you’ll need to carry out in order to create such an application, and help you understand the kinds of information you’ll be expected to provide (and where you’ll have to provide it). 

To create a SAML authentication application for Okta, complete the following procedure:

1. Log on to the Okta developers center. From the Dashboard page, in the navigation pane, expand Applications and then click the second Applications link:

   

2. On the Applications page, click Add Application:

   

3. On the Add Application page, click Create New App:

   

4. On the Create a New Application Integration page, select Web from the Platform dropdown, select SAML 2.0 as the Sign on method, and then click Create:

   

5. On the Create SAML Integration page, on the General Settings tab, enter a name for your new application:

   

6. To display a custom logo in the Okta sign-in dialog, click the browse button in the Add logo section:

   

7. Select the desired logo file from the File Select dialog and then (at least on a Macintosh) click Open:

   

   The file name appears next to the Browse button:

   

8. To assign the logo to your app, click Upload Logo.

9. Click Next:

   

10. On the SAML Settings tab, enter your ACS URL (redirect/callback URL) in the Single sign on URL field (be sure that the Use this for Recipient URL and Destination URL checkbox is selected):

    

    See the article Create a custom provider for information on how to construct your ACS URL. This same value should be entered in the Default RelayState field.

11. Enter your Entity ID in the Audience URI (SP Entity ID) field. Again, see Create a custom provider for information on how to construct your Entity ID.

12. In the Attribute Statements section, map the Okta user profile attributes you want returned in the SAML assertion to their corresponding Identity Cloud attributes. For example:

    

    To map the attributes, type the Identity Cloud attribute name (e.g., displayName) in the Name field. (Be sure to use the correct letter casing when entering the attribute name.) Leave the Name format set to Unspecified, then enter the Okta attribute name in the Value field. The Okta attribute name must be prefaced with user. (including the period after the word user). This syntax means that the value will be extracted from the Okta user profile.

13. After you have mapped the attributes, click Preview the SAML Assertion:

    

    The preview shows you what the SAML assertion returned after a successful authentication will look like. Among other things, verify that the attributes you just mapped appear in the assertion:

    

14. Click Next:

    

15. On the Feedback tab, select I’m an Okta customer adding an internal app. Select This is an internal app that we have created, and then click Finish:

    

16. After the app has been created, click View Setup Instructions:

    

    Metadata for your new app is displayed:

    

    When you create the custom provider for Okta, the value of the Identity Provider Single Sign-On URL field will serve as the value of the auth_url property, and the value of the X.509 Certificate field will serve as the value of the idp_certificate field. Because of that, you might want to copy and save those values.

17. On the home page for your application, click Assignments:

    

18. Click Assign, then click Assign to People or Assign to Groups as appropriate:

    

19. Locate the users (or groups) who are allowed to use the new app, and click Assign next to the user/group name:

    

20. After you’ve made all your assignments, click Done.

At this point, your Okta app is complete, and you’ll be ready to create your custom provider.