Configure Application Authentication¶

Vinyl supports Application Authentication as a security provider type. Application Authentication allows developers to build their own login forms. Developers can authenticate clients using an approach suitable to the application.

You may want to configure Application Authentication if, for example, you want your application to:

• Maintain their own user accounts
• Validate credentials with a third-party
• Verify a phone number by texting a One-time Passcode (OTP)
• Allow clients to sign in semi-anonymously

Application Authentication Requirements¶

The following information needs to be configured within each Environment that the App resides in (e.g., Dev, QA, Production) for Application Authentication to work properly:

• Login page configured as a separate application
• App Authentication Security Provider Group
• Generic User Account(s)
• Groups with Roles assigned
• Vinyl Realm configured for App

In addition to the above requirements, within the App itself you'll need to configure:

• Authenticate Rule
• Session Table with Login Fields
• Optional: Password Validation
• App Level User Table
• Vinyl as a Data Source added to the App and Linked to your primary Data Source

Configure Login Page as Separate App¶

The Login page should be configured as a standalone Application within your application environment, and built off of the same data source as your primary Application. It will only be used for authentication purposes, and therefore needs access to the User credential data.

This Login page is fully customizable. There is some information required on this page (listed below) and you may wish to add additional information as needed by your specific app requirements.

Login Page Requirements¶

• Panel designed to run off of Session
• Entire Page must be accessible by the Anonymous User
• At a minimum, page requires a User Name field (editable)
• Optionally you may include a Password field (can have Password Validation configured)

• Button that allows User to fire off the Authentication Rule built for Application Authentication. For example: Login.

  Note

  This Button should not link to any Pages. It should only run the Authenticate Event which will then automatically load the Vinyl page set as 'Default Page' in the Security Provider settings.

• Optional: Forgot Password link, Sign up link

Application Authentication Security Provider¶

The Application Authentication Security Provider needs to be configured for the application.

To Configure the Application Authentication Security Provider¶

1. Navigate to the IDE
2. Select Security Providers

3. Click + User Authentication under the User Authentication panel, and Name the Security Provider. Generally this is Named after the application it is provisioning for. For example: ApplicationManager.

   • Type = Application Authentication
   • Priority = autogenerated by Vinyl
   • Enabled = must be enabled to be used. Leave this setting off (disabled) until all required information is configured, and you're ready to test Application Authentication.
   • Identifier = autogenerated by Vinyl. If you're parameterizing this information, this is what should be on the Parameter table as the Provider ID.
   • Under the Authentication section, select Show on Login Form.
   • For Default Page, select the Page you want a User to go to in your Application after authenticating from the Login Page. If you don't see the Page you want from the list initially, navigate back into your Application and make the Page Shared and come back to select it.
   • Provisioning is not recommended to be populated

4. Click + Property under Properties. Select LoginPath as the Parameter, and for the Value itself browse to the application Authentication login page and select the URL after the Domain Name.

   • Be sure to include the leading slash with the information you copy from the URL. For example: /app/Application%20Manager%20LogIn/LogIn%3F%24activepanel%3DA?$activepanel

5. Save the record

Generic User Accounts¶

In order to use Application Authentication you need at least one User Account created for this purpose, you may want to have more than one User Account depending on your app requirement. Create a Vinyl User(s) and name them corresponding to the level you want them to see within the app after authenticated. For example: ApplicationManagerUser, ApplicationManagerDeveloper, ApplicationManagerAdministrator.

The User Account is what Vinyl uses to take the specified User and authenticate them. If you require Groups assigned to Users who are authenticated through this created User Account, you should add the Group(s) at this stage.

Next you'll create an Identity for the new User(s). This is where you select the Provider group which is the Application Authentication provider you created, the User (the actual Vinyl user and should be defaulted), and a Name. The Name is the actual Name of the Identity you've created. Often the Name is the same as the User. Identifier does not need to be defined.

Vinyl Realm Configured for App¶

• A Realm must be configured containing your application and the application Login app
• This Realm should contain any Groups used by the App Authentication Users
• The Application Authentication Security Provider will also be part of the Realm

For more information on Realms and configuring them, see the Realms article.

Authentication Rule¶

Next you'll configure an Authentication Rule to be used by Application Authentication. Build a CRUD XP Business Rule that Targets the Authenticate view from the Vinyl Data Source. The Source Data Source should be the apps primary Data Source, and the Target Data Source will be the Vinyl Data Source, the Action will be Insert. Name this Rule something like Authenticate (User Authentication).

When you go to design the CRUD Rule in Business SQL, you'll need to bring in the User table (the table storing your User credentials), the Session table, and depending on how you store what User is signing in as what, you may want to bring in an additional table(s) such as Parameter.

The Inner Join in this scneario is on the User Name you want them to be using, so that if the User Name equals something on that table the User will be able to log into the app. If Password Validation is also being setup, it would be on the same Event as this CRUD XP Rule.

The following 4 Columns are required to be configured for the Authentication Rule:

1. The Rule must have a newly generated GUID (newUUID()) configured to Target AuthenticateID
2. The ID of the Application Authentication security provider, this should Target ProviderId
3. The Rule needs whatever you are passing as the application User Name. This is what tags the User so Vinyl knows who the person who signed in is. This is what's being used by Auditing in Vinyl. It's recommended to use Email or User Name, and this Column should Target AppUserId.
4. A Provider User Name, this is the User that they get provisioned access to in the app. This can be dynamic or hard-coded but is required and should Target the Name.

Enable Security Provider¶

Lastly, with all the information described in this article configured, you should be able to Enable the Security Provider and test to see that Application Authentication is now working for your app.

Optional Configuration for Handling Non-Authenticated Users¶

When a non-Authenticated User navigates to a page where Application Authentication is enabled, you can control where Vinyl redirects them. If you want a User redirected to the standard login page, where they can select a link to get to the app login page, then no additional setup is required. If, however, you want a User redirected to the application login page automatically, there are 2 additional settings required:

1. Default Authentication - This tells Vinyl which security provider you want to use to authenticate users within a given application.
2. Redirect On Challenge - This tells Vinyl to skip the login form when redirecting users to your Application Authentication provider.

To Configure the Default Authentication Provider¶

1. Sign into Vinyl as an administrator User
2. Click the IDE button
3. Click the Security Providers button
4. In the User Authentication panel, click More > Manage Applications
5. Click the Edit icon (Pencil) for the application
6. Set Default Authentication to the Application Authentication provider
7. Click the Save button

To Configure Redirect On Challenge¶

1. Click the Back button to return to the Security Providers page
2. In the User Authentication panel, click the Details icon (Chevron) for your Application Authentication provider
3. Click the Edit button
4. Check the Redirect On Challenge option
5. Click the Save button

Resources¶

• Security Provider - Application Authentication