Configuring Okta¶

Okta is an Identity Provider (IdP) which supports SAML Single Sign-On (SSO) authentication. Vinyl integrates with Okta as a Service Provider (SP). Each Vinyl instance must be integrated with Okta and vice versa. There are three main tasks involved:

1. Register Vinyl as an Okta application.
2. Configure Okta as a Vinyl security provider.
3. Map Vinyl users to Okta identities.

It's assumed that your organization already has an existing Okta account.

The instructions below will refer to the following properties:

Register Vinyl as an Okta Application¶

The following Okta document describes how to register a SAML application: https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta

1. During the setup process, you will be prompted for the following information:

   • Name: Vinyl environment name.\

     Example: Vinyl Development

   • Single sign-on URL: Corresponds to the Assertion Consumer Service URL.\

     Example: https://example.com/Vinyl/signin-Okta

   • Audience URI: Although the audience URI is arbitrary, Okta and Vinyl must use the same Audience URI. Consider using the the Vinyl App URL.\

     Example: https://example.com/Vinyl/.

   • Name ID format: EmailAddress

   • Application username: Okta username

2. You may supply optional Attribute Statements or Group Attribute Statements claim mappings. Commonly mapped claims include:

   • Email Address - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
   • Group Membership - http://schemas.xmlsoap.org/claims/Group

   Note

   See Claims for additional information regarding claims.

3. Click Next, select I'm an Okta customer adding an internal app, and click Finish.

4. Once the Okta application has been created, copy and store the following values for reference later:

   • Metadata URL. Example: https://www.okta.com/app/abcdef012345/sso/saml/metadata
   • Sign on URL. Example: https://example.okta.com/app/abcdef012345/sso/saml
   • Issuer. Example: http://www.okta.com/abcdef012345

Configure Okta as a Vinyl Security Provider¶

To configure Okta as a Vinyl security provider, start by signing into Vinyl as an administrator.

1. Navigate to the IDE
2. Select the Security Providers button
3. In the User Authentication panel, click the + User Authentication button

4. Provide the following:

   • Name: Security Provider Name (see above)\

     Example: Okta

   • Type: SAML

   • Enabled: Check

5. Click the Save button

6. In the Tokens section, provide the following:

   • Audience: Audience URI (see above)

     Example: https://example.com/Vinyl/

   • Recipient: Single sign-on URL (see above)

     Example: https://example.com/Vinyl/signin-Okta

   • Issuer: Issuer (see above)

     Example: http://www.okta.com/abcdef012345

7. Click the Save button

8. In the Provisioning section, confirm the following settings:

   • User Provisioning: Check
   • Supplies Group Membership: Check
   • Store Claims: Check

9. In the Endpoints panel, click the + Endpoint button

10. Provide the following:

    • Type: Metadata Endpoint

    • URL: Metadata URL (see above)

      Example: https://www.okta.com/app/abcdef012345/sso/saml/metadata

11. Click the Save button

12. In the Claims panel, you will need to map any claims from Okta in Vinyl. For example, to map the Group and E-mail Address claims, click the + Claim button

13. Provide the following:

    • Identifier: Claim type name.

      Example: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/Group

    • Usage: Claim type usage.

      Example: Group

14. Click the Save button

15. Exit the Claim screen and click the + Claim button from the Claims panel

16. Provide the following:

    • Identifier: Claim type name.

      Example: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

    • Usage: Claim type usage.

      Example: E-mail Address

17. Click the Save button

18. In the Sign In section, check to enable Show On Login Form. This enables a Sign in with Okta button to display on the Vinyl login page.
19. Click the Save button

Map Vinyl Users to Okta Identities¶

With User Provisioning¶

If you've enabled user provisioning as described above and attempt to sign in, you may be redirected back to the Vinyl login form with the following message:

The user account (arthur.dent@example.com) has not been granted access to an application.

Although Vinyl was able to successfully provision the user, the user does not have access to any Vinyl applications by default. Assuming the Okta user has been added to one or more groups and that Supplies Group Membership is enabled (as described above), you will need to map the Okta security groups to Vinyl security groups.

To map Okta security groups to Vinyl security groups, start by signing into Vinyl as an administrator.

1. Navigate to the IDE
2. Click the User Management button
3. Click the Identities tab
4. In the Provider Groups panel, locate the Okta group and click the Details icon (Popup)
5. Click the Edit button
6. From the Group list, select the Vinyl group
7. Click the Save button

Please see the User and Group Provisioning for additional information.

Without User Provisioning¶

If you have not enabled user provisioning, authentication will have failed with a message similar to the following:

Although you've successfully authenticated with Okta, the account arthur.dent@example.com (arthur.dent@example.com) is not associated with a local account.

In the message above, arthur.dent@example.com is the Okta User Name (called "name" in claims authentication). The part in parenthesis is the Okta Name Identifier (called the "name identifier" in claims authentication). You'll need these two pieces of information for the next step.

To map a Vinyl user account to an Okta identity, start by signing into Vinyl as an administrator:

1. Navigate to the IDE
2. Click the User Management button
3. In the Users panel, locate and select the user you would like to map
4. In the Identities panel, click the + Identity button

5. Provide the following:

   • Provider: Security Provider Name\

     Example: Okta

   • Name: Okta User Name (see above)

   • Identifier: Okta Name Identifier (see above)

6. Click the Save icon (Check)

Troubleshooting¶

The user is redirected back to the login page after signing in.¶

If User Provisioning has been enabled, then the user may have been created but not assigned to any groups or the groups that the user has been assigned to have not been granted access to any Vinyl applications. The only group assigned to new users by default (i.e. has the Grant On User Create option enabled) is the Users group. This group is not granted access to any applications by default.

If the Supplies Group Membership option has been enabled, Vinyl will have registered the Okta groups. Sign in as an administrator and map the Okta groups to Vinyl security groups. If the Supplies Group Membership option has not been enabled, the Okta security provider will not have any groups. Sign in as an administrator and define one or more Okta security provider groups with the Grant On Identity Create option enabled and map the provider groups to Vinyl security groups.

If the Require HTTPS security provider has not been enabled, the user may initiate the SAML SSO process from a non-secure URL (e.g. http://example.com/Vinyl/). However, the Identity Provider will return the user to the secure Assertion Consumer Service (ACS) URL (https://example.com/Vinyl/signin-Okta). Vinyl authenticates the user in the context of the secure URL before returning the user to the non-secure URL. In effect, the user has two separate sessions. To address this issue, enable the Require HTTPS security provider.

The Okta application may be deactivated.

Error: "The AudienceRestrictionCondition was not valid because the specified Audience is not present in AudienceUris."¶

This error indicates that the audience URI does not match. Ensure that the Audience property has been explicitly set. If not set, it will default to the current URL, which may vary by user. The value is case-sensitive.

Error: "An unhandled exception was caught at the end of the pipeline."¶

This error can indicate a mismatch between the configured Recipient value and the expected Recipient value in Vinyl. Ensure that the Recipient value is configured properly.