Deprecation notice: We strongly recommend using the App Integration Wizard in lieu of this template app for creating new SAML 2.0 integrations through the UI. The SAML App Wizard is both more powerful and easier to use than the templates, and will improve significantly over time. This page is no longer being updated and may not show current information.
Please note that the ability to create new templates will be restricted in the future; however, existing templates will continue to be supported.
Okta provides two SAML template apps (SAML 1.1 and SAML 2.0) through which you can create SAML enabled apps, on demand.
When using these template applications, Okta acts as the IDP (identity provider) and the target application will be the SP (service provider).
For SAML 2.0, Okta (acting as the IDP) supports 2 methods of authentication:
In IDP initiated the flow is:
- User goes to Okta (assumption is that the user has an existing Okta session)
- User clicks on the Chicklet and this sends a SAMLResponse to the configured SP
- A session is established with the SP
- User is authenticated
In SP initiated the flow is:
- User goes to the target SP first. They do not have a session established with the SP
- SP redirects the user to the configured Login URL (Okta’s generated app instance url) sending the SAMLRequest.
- Okta is sent SAMLRequest (assumption is that the user has an existing Okta session)
- Okta sends a SAMLResponse to the configured SP
- SP receives the SAMLResponse and verifies that it is correct. A session is established on the SP side.
- User is authenticated
In both cases, there is additional configuration required in the target app (SP) you are configuring SAML with. Okta provides this information in our SAML 2.0 app instructions (accessible from the Sign on tab in the app wizard). This is typically the following: External key, certificate, and login url (normally only needed in the SP initiated flow mentioned above. App dependent. We recommend you check with your SP vendor to see if turning on SAML is an all or nothing feature.
Configuring Template SAML 2.0
The first thing you’ll need to do is to add the Template SAML 2.0 app to your org.
- Login to the Okta admin app, go to Applications, click on the Add Application button and select Template SAML 2. 0 App
- In the Template SAML 2.0 app, you’ll need to complete the following fields. You will need to look at the target application’s (SP) documentation to get infomation for some of these fields.
- Application Label – Give your app a label that will display on your users homepage
- Name ID format – The value you choose will depend on the application – this is the username format that you are sending in the SAMLResponse. Consult the SP documentation to determine what format to use.
- Recipient – Enter the service provider’s assertion consumer service URL. Consult the SP documentation to get this information.
- Audience Restriction – This is the entity id of the Service Provider. It will be provided by the SP and must match exactly. Consult the SP documentation to get this information.
- authnContextClassRef – This tells you the type of authentication restriction. This will typically need to be set to Password Protected Transport . Consult the SP documentation to get this information.
- Destination for the SAML response – This is the intended destination of the saml assertion. Unless specified by the SP, this will typically be identical to the post back URL. Consult the SP documentation to get this information.
- Response – Allows you to control if the SAML response will be signed or unsigned – this depends on the app. Consult the SP documentation to get this information.
- Assertion - Allows you to control if the SAML assertion will be signed or unsigned. Consult the SP documentation to get this information.
- Request – This option depends on the app and allows you to control whether the SAMLresponse is compressed. Consult the SP documentation to get this information.
- Post Back URL – This is the SAML SP endpoint (i.e. where your users will log in) For example, http://test.acme.com/example-post-sign/
- Default Relay State (Optional) – This is the page your users will land on after they successfully login (via SAML) into the SP. This can be left blank or if provided, should be a valid url. Consult the SP documentation to get this information.
- Force Authentication (Optional) - When selected, your users will be prompted for their credentials when a SAML request has the ForceAuthn attribute set to true, even if they are already logged in to Okta (They will need to enter their credentials even if they normally login through Desktop SSO). If this box is left unchecked the flag will be ignored.
- Attribute Statements (Optional) – You can federate Okta user profile fields, LDAP, Active Directory, and workday values to SAML attributes. The SP will use the federated SAML attribute values accordingly. Click on the App’s sign on tab, SAML 2.0 instructions to see the list of available attributes, usage, and examples. See Mapping Active Directory, LDAP, and Workday Values in a Template SAML 2.0 or WS Fed Application for more information.
- Group Name (Optional) –Enter in name for this attribute that will be included in the SAML response attribute statement (This essentially turns the option on). You’ll need to then enter in the groups (using expressions) in the group filter field to specify which groups will be included with this attribute. Any users that belongs to the group you’ve filtered will be included in the SAML Response attribute Statement (Optional)
- Group filter (Optional) – Specify which groups you want included with the attributed you named in the Group Name field by entering expressions that will be used to filter groups. For example app1.* means all groups prefixed with that string will be included in the SAML Response attribute statement. (optional)
- Application Visibility (Optional) – You can choose to hide the application from your users homepage.
Configuring SAML in the target application (SP)
In order for SAML to work, there is additional configuration needed in the target application (SP).
Note: We recommend that you call the vendor for the SP and determine if enabling SAML is an all or nothing option. Okta provides all of the necessary configuration information you need to make in the target SP.
To access this information, do the following:
- Click on the instance of the template app you added.
- Click on the Sign-on tab and click on the SAML 2.0 Setup instructions for Template SAML 2.0 link.
- Scroll to the Configuration Data section and you'll be able to get all the necessary SP endpoint configuration information.
Assign a user to the app and verify that they are able to authenticate successfully.