Configuring Auth0¶

Auth0 is an Identity Provider (IdP) supporting several authentication protocols, including SAML Single Sign-On (SSO) authentication. Vinyl integrates with Auth0 as a Service Provider (SP). Each Vinyl instance must be individually integrated with Auth0 and vice versa. There are three main tasks involved:

1. Register Vinyl as an Auth0 client.
2. Configure Auth0 as a Vinyl Security Provider.
3. Map Vinyl users to Auth0 identities.

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

The instructions below will refer to the following properties:

Register Vinyl as an Auth0 Client¶

To register Vinyl as an Auth0 client, start by signing into the Auth0 dashboard as a Dashboard Administrator.

1. Select the Clients menu link.

   

2. Click the Create Client button.

   

3. Provide the client Name.

4. For the Client Type, choose the** Regular Web Applications**.
5. Click the Create button.
6. Click the Addons tab.

7. Select the** SAML2 Web App** option.

   

8. For the Application Callback URL, provide the Assertion Consumer Service URL.

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

9. Click the Usage tab.

10. Note the Identity Provider Metadata URL–i.e., right-click the Download link and choose Copy link address.

    https://example.auth0.com/samlp/metadata/aBcDeFgHiJkLmNoPqRsTuVwXyZ

11. Click the Save button.

    Note that single sign-on (SSO) is not enabled by default. If you require single sign-on:

12. Click the Settings tab.

13. Enable the Use Auth0 instead of the IdP to do Single Sign On option.

    

14. Click the Save button.

Configure Auth0 as a Vinyl Security Provider¶

To configure Auth0 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 Data Source Authentication panel, click the + Data Source Authentication button

4. Provide the following:

   • Name: {Security Provider Name}

     Example: Auth0

   • Type: SAML

   • Priority: A unique integer between 10 and 100. Note that this value must be unique.

     Example: 50

   • Enabled: Check

   • User Provisioning: Check to enable just-in-time user provisioning
   • Supplies Group Membership: Check if Auth0 has been configured to pass user group membership.
   • Redirect on Challenge: If this is enabled, the web client will bypass the login form, redirecting the user to the OAuth provider
   • Show On Login Form: Check

5. Click the Save button

6. In the Properties panel, click the + Property button
7. From the Parameter selection list, select MetadataEndpoint

8. For the Value, provide the {Identity Provider Metadata} link (see above).

   Example: https://example.auth0.com/samlp/metadata/aBcDeFgHiJkLmNoPqRsTuVwXyZ

9. Click the Save icon (Check)

Map Vinyl users to Auth0 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.

Though Vinyl was able to successfully provision the user, the user does not have access to any Vinyl applications by default. Assuming the Auth0 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 Auth0 security groups to Vinyl security groups.

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

1. Navigate to the IDE
2. Select the User Management button
3. Click the Identities tab
4. In the Providers panel, locate and select the Auth0 security provider
5. In the Provider Groups panel, locate an Auth0 group you would like to map and click the Edit icon (Pencil). If it does not appear, click + Group and configure a record accordingly.
6. Select the Vinyl security Group to which the Auth0 group will be mapped
7. Click the Save button

Please see the section on Identity and Group mapping for more 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 Auth0, the account arthur.dent@example.com (auth0|aBcDeFgHiJkLmNoPqRsTuVwZyZ) is not associated with a local account.

In the message above, arthur.dent@example.com is the user name (called "name" in claims authentication). The part in parenthesis is the unique 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 Auth0 identity, start by signing into Vinyl as an administrator:

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

6. Provide the following:

   • Provider: Auth0 (or the name chosen in the previous section)
   • Name: The Auth0 user name (see above)
   • Identifier: The Auth0 name identifier (see above)

7. Click the Save icon (Check)

Troubleshooting¶

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

1. If 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 any Auth0 groups passed via a SAML assertion. Sign in as an administrator and map the Auth0 groups to Vinyl security groups.
   • If the Supplies Group Membership option has not been enabled, the Auth0 security provider will not have any groups. Sign in as an administrator and define one or more Auth0 provider groups with the Grant On Identity Create option enabled and map the provider groups to Vinyl security groups.

2. 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/). However, Auth0 may return the user to the secure Assertion Consumer Service (ACS) URL (https://example.com/signin-Auth0). 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.